rdoc problem

[Henry Savr]

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
<tt>rdoc1</tt>
<b>rdoc2</b>
= 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 <em>outside<em> the block
# <tt>rdoc1</tt>
# <b>rdoc2</b>
# = Level 1
# == level 2
# === Level 3
# ==== Level 4
# ===== Level 5
#
# extra comment
# <tt>rdoc1</tt>
# <b>rdoc2</b>
#
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

 

[David Vallner]

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

#!ruby

#= Usage
#
#<tt>hello.rb</tt>
#
#This script outputs "Goodbye, cruel world!" to standard output.
#
#== Parameters
#
# 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 Vallner

 

[David Vallner]

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 Vallner

 

[Rick DeNatale]

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/

 

[Eric Hodel]

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
<tt>rdoc1</tt>
<b>rdoc2</b>
= 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 <em>outside<em> the block
# <tt>rdoc1</tt>
# <b>rdoc2</b>
# = Level 1
# == level 2
# === Level 3
# ==== Level 4
# ===== Level 5
#
# extra comment
# <tt>rdoc1</tt>
# <b>rdoc2</b>
#
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?

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

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

 

[Dave Howell]

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

 

[Eric Hodel]

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

Lies.

$ ri RDoc | grep 'processed by RDoc'
be processed by RDoc.

 

[David Vallner]

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.

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 Vallner

 

[Henry Savr]

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

 

[Rick DeNatale]

- 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