Rdoc problem

Ruby
1

Playing with rdoc, I found, that it works ONLY for =begin/=end rdoc
block. More, if the file starts from regular comment #, even the block
=begin/=end does not work.
Please, help

This is the code:
<<<<CODE STARTS (this line is NOT included into the code>>>>
=begin rdoc
My path is c:/PJ/play/test/lib/test/
This is a rdoc text inside block
rdoc1
rdoc2
= Level 1
== level 2
=== Level 3
==== Level 4
===== Level 5

section

=end

puts “rdoc text 1”

My path is c:/PJ/play/test/lib/test/

This is a rdoc text outside the block

rdoc1

rdoc2

= Level 1

== level 2

=== Level 3

==== Level 4

===== Level 5

extra comment

rdoc1

rdoc2

puts “rdoc text 2”
<<<<CODE ENDS (this line is NOT included into the code>>>>

Only the first part is shown on output
More, when I copied the second part and put it before the fist one,
having so 3 parts, the output gets empty.

What could be wrong?
Thank you.
Henry

2

Henry S. wrote:

Playing with rdoc, I found, that it works ONLY for =begin/=end rdoc
block. More, if the file starts from regular comment #, even the block
=begin/=end does not work.
Please, help

Couldn’t reproduce the problem.

The script

None

puts “Goodbye, cruel world!”

gives me correct HTML rdoc output.

I couldn’t get =begin/=end comments to work, I don’t even know if rdoc
supports those - it might rely on indentation of the # signs or
something like that.

David V.

3

Henry S. wrote:

Only the first part is shown on output

Also…

Only that one is supposed to be there. Rdoc looks for file-specific
documentation as the first documentation segment in the file - it’s not
supposed to process every comment in the file.

David V.

4

On 8/28/06, David V. [email protected] wrote:

Henry S. wrote:

Only the first part is shown on output

Also…

Only that one is supposed to be there. Rdoc looks for file-specific
documentation as the first documentation segment in the file - it’s not
supposed to process every comment in the file.

Actually it’s supposed to process the first comment block before each
“major element” in the file. The pickaxe 2nd ed. “defines” major
elements as (classes, modules, methods, attributes, and so on).

I’m not sure where the official list of major elements can be found.

–
Rick DeNatale

My blog on Ruby
http://talklikeaduck.denhaven2.com/

IPMS/USA Region 12 Coordinator
http://ipmsr12.denhaven2.com/

Visit the Project Mercury Wiki Site
http://www.mercuryspacecraft.com/

5

On Aug 28, 2006, at 11:28, David V. wrote:

I couldn’t get =begin/=end comments to work, I don’t even know if rdoc
supports those - it might rely on indentation of the # signs or
something like that.

From RDoc’s (hidden) README file:

Comment blocks can be written fairly naturally, either using ‘#’ on
successive lines of the comment, or by including the comment in
an =begin/=end block. If you use the latter form, the =begin line
must be flagged with an RDoc tag:

=begin rdoc
Documentation to
be processed by RDoc.
=end

6

On Aug 28, 2006, at 10:29 AM, Henry S. wrote:

rdoc1
=end

==== Level 4

More, when I copied the second part and put it before the fist one,
having so 3 parts, the output gets empty.

What could be wrong?

Without a class or module you should get no documentation at all.

Please give the command you are using to generate the documentation.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

7

Rick DeNatale wrote:

Note the “file-specific”. The file itself being the documented element.

Though I admit what I said might have been confusing at a glance.

David V.

8

On Aug 29, 2006, at 2:40 PM, Dave H. wrote:

an =begin/=end block. If you use the latter form, the =begin line
must be flagged with an RDoc tag:

=begin rdoc
Documentation to
be processed by RDoc.
=end

Lies.

$ ri RDoc | grep ‘processed by RDoc’
be processed by RDoc.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

9

On 9/2/06, Henry S. [email protected] wrote:

  • I used them after second statement of every class and module
    You normally put rdoc commentary BEFORE the thing you want to document
    e.g.

#MyClass is a class which

…

class MyClass

 # method1 does blah blah blah
 def method1(args)
    ...
 end

end

–
Rick DeNatale

My blog on Ruby
http://talklikeaduck.denhaven2.com/

10

Thanks for trying to help

Here are some details

  • using =begin \ =end described in “Programming Ruby. Second Edition”
  • I used them after second statement of every class and module
  • I generated rdoc using the command rdoc sometimes with -S and/or -w4
    All parameters produced the same result: The first # turns off
    generating. FF and IE browsers show the same. I use Windows with 1.8.4