From: Igor Pirnovar <gooigpi@...>
Date: 2009-02-21T02:50:26+09:00
Subject: Re: How does one generate a "main page" for rdoc documentation?

James Britt wrote:

> Without telling rdoc what files to treat as "main", you 
> may be surprised which file it picks if you have more 
> than one.

You must be a rather disorganized computer ... Each project that 
deserves to be processed with rdoc should be in a separate directory, 
and there will be absolutely no surprise what file rdoc will pick up. 
All of you guys seem to have missed the main idea behind the rdoc, which 
is to convert the in-line comments to external documentation.

Joel VanderWerf wrote:

> That's not the only way to do things. I like a separate 
> README so that someone can find a top-level, greppable help 
> file without going to the rdoc or digging in lib/. Also, 
> I don't like all that extra front matter in my class 
> definitions.

The rdoc package documents have three sections: Files, Classes and 
Methods, and for each of them rdoc creates a separate "html" file which 
are then managed from the top level index.html.  The file level / header 
documentation may be included in every file an is what is what I above 
called the application doc. All these different pieces of info are 
displayed under the Files, Classes, and Methods sections at the top of 
the rdoc web-page, so you can choose what you are interested in by 
clicking on the individual items there. Indeed, you can create a 
README.rb, HEADER.rb or anything you like to pack in and squirrel away 
the header (application level) documentation, but that defeats the 
original rdoc strategy which is document as you go - converting the 
in-line comments to documentation. If you follow the rdoc rules you will 
end-up with a pretty decent documentation without the need for too much 
extra efforts, as long as you have the discipline to document what you 
are doing.

That is how rdoc works, and there isn't very much you can do about it. 
Yes, I would like it to provide a directive to include images, for 
instance, I sometimes add class and object diagrams, but in order to do 
that you have to tweak the doc/*.html. In fact, one day I may add just 
such an extension for rdoc myself, unless someone else doesn't take my 
advice and does it for me ;)
-- 
Posted via http://www.ruby-forum.com/.