Documentation with RDoc

Generating documentation with RDoc

We’ll suppose that your application is a Rails application.

1. Go to the root of your application
2. Type rake doc:app

This rake task (that uses RDoc) will start generating the documentation for your application. It will detect every controllers, every models, every helpers, every methods, every attributes, every constants, every whatever and will structure all of this in a logical manner. Then, it will output a bunch of HTML files that you will find in doc/app. Moreover, it will detect every comments you wrote and try to include them at the right place in the doc.

Syntaxes and Examples to do comments on your applications :

Text Decoration :

This method is a very critical one in our system. Please be careful!

The text above is bigger because I used 2 heading characters "==" before typing the actual comment. (It‘s like the h1, h2, h3 tags in HTML but instead you use =, ==, === and so on)

Ordering:

1. It takes 2 params
2. We discard the 1st one
3. We put "mister t" in the second one if nothing has been supplied.

As you can see, you can also create ordered lists with RDoc. Just type a digit and then a period before your comment. If you need a non-ordered list, type * or - before your comment. If you need an alpha list, type a letter followed by a period. Note also that RDoc automatically put hyperlinks around method and class names. That‘s a very easy and useful way to help people navigating in your documentation! Hey let‘s try it…

Hyperlink :

RDoc also detects external links, like www.railsthinker.blogspot.com. If you prefer displaying a label instead of an URL address, use the label[url] format instead, like that : www.railsthinker.blogspot.com. If your label as more than 2 words (like in the example), put them inside curly braces, like that {Rock on!} [the url]

HTML basic formatting :

Finally, how about some HTML basic formatting? if it is just one word long, use * hello * for bold and _ hello _ for italic (just remove the spaces). Now if the thing to format is more than one word long, use the more traditionnal and <em> and <b> tags (just a nitpicky question though : Why "b" instead of "strong"?).

One final note :

RDoc is not specific to Rails. Like I said earlier, it is a ruby library and thus you can use it in other contexts. I took Rails because I knew that the % of people using Ruby without Rails was rather small.