Documenting used to be a pain

This will stay between you and me I promise : How many of you take the time to write complete and meaningful documentation for your applications? It seems to always be the last thing we want to work on or think about. There are many reasons for that, but the most obvious is because documentation is not mandatory for your application to work… so it’s easy to “forget”. It’s way more exciting to code new features, improve the design, refactor some old code, drink Buckley’s syrup, roll discretely on the floor pretending you are Rambo and so on than it is to document your application. But the fact doesn’t change : Having good documentation for your application is important. Without a good tool to help you create documentation that is dynamic, structured, easily editable, consistent and visually pleasing, it will take you forever because you will have to do it by hand. And even if you’re crazy enough to do that, it will have taken so much of your time that just thinking about doing it again for your next project will make your nose bleed… and ultimately you will start to regret the day you choose to become a developer.

RDoc to the rescue

RDoc is a ruby library that generates documentation for you. What is great with RDoc is that it gives you some basic documentation “out of the box” for your application without you having to do anything. Like with many other existing tools, RDoc parses your code and try to understand its structure. Then, it produces a nice HTML formatted documentation that allows you to navigate between the various classes, methods, attributes of your code.

Generating documentation with RDoc could not be easier

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. For example, if you wrote a comment just above a method, RDoc will presume that this comment describes what this method is doing. Clever RDoc, clever…

While it generates the files, sit back and think about how competent and professional you will look with this great documentation. After that, open yourapp/doc/app/index.html in your favorite browser and laugh in a sinister way (if you are alone). Finally, send an email to your boss/employee/friend/camel with the compressed files attached to the message and tell him that “you have just finished working on a complex and interactive knowledge base system that will help the other human resources of your department to become more efficient while using, modifying and adding new functionalities to the core application”. That should impress him for years to come. Please note that this paragraph was completely useless.

Using RDoc to your advantage

RDoc recognizes a certain commenting syntax that you can use in your ruby source files to increase the quality of your documentation. You can ignore this syntax and write your comments like you always did… but you can also choose to benefit from a richer and cleaner documentation without much more effort on your part. In fact, it will take 5 minutes of your life to learn the basic syntax. It’s that simple really. Here is a small demo I made that shows how RDoc is great to produce clean and well organized HTML documentation. I’m sure you’ve seen a lot of RDoc generated doc already, but what I want to show you here is how to write ruby comments that are RDoc-friendly. In other words, I used RDoc to show you how RDoc works.

Here is the demo

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.

(No Ratings Yet)

 Loading ...