Ruby has another excellent document preparation tool, RDtool. Its philosophy is different to that of RDoc. While RDoc is unashamedly a source code documentor, RDtool is a more general markup language that knows nothing about source code. If you use RDtool to document source, you place markup between =begin/=end pairs. RDoc on the other hand parses source files, extracting class, module, attribute, and method definitions.
So, which should you use, RDtool or RDoc? It depends totally on your personal preferences. If you are writing a large, standalone document, I'd say RDtool has the edge. If you're writing documentation in your code, then I personally much prefer RDoc: I find it clutters the source a lot less. (The fact that it also documents methods even if you haven't written any explicit documentation for them is also a plus!)
To help you decide, I've posted some examples of the two. I took cgi.rb from the standard distribution and converted its RDtool comments to RDoc so you can see them side by side.
|Source file||Source file|