Where in the world are the comments ? Ruby on Rails code documentation, a minimal convention proposition

Of Lately we have been churning more and more Ruby on Rails code for our web applications. Its source-code is becoming longer and longer. It was time for us to think about formalizing the documentation process.

After a short search, we found rdoc and it seems to suit our needs. It has good source-analysing basis and interesting features such as diagram generation. The problem came from rdoc youngness which led to two issues :

  • the lack of documentation, the only relevant document is the rdoc's README file
  • In fact, there are no standards nor conventions on tags to describe a parameter, an instance variable, the author of the code or anything else

We had to understand that this

#Author::  author's name

is not a tag. It's just a syntax for something to be parsed as a definition list.

So we decided to make our own convention, trying to be as near as possible to existing documentation conventions while banking on the emergence of a hypothetical future standard. So we looked at the Ruby source-code, seeking for its developpers conventions. Guess what… There are no comments in Ruby code nor in rdoc's one (or very few, almost none are structured).

So… we were forced to set out to do our own convention. As we do a lot of PHP code, we decided to use the inspiration of the JavaDoc inspired phpDocumentor syntax and PhpDoc tag names. We added the :: to keep compatibility with rdoc and we added home-made syntax rules such as the ## to spot the begining of a comment readable with our new convention. And the result is…

#Class' description
#@author::          name of the code's author
#@usage::           what this class is about to, how to use it
#@copyright::       name of the right's owner
#@licence::         URL of a licence
#@revision::        date of the last revision
#@documentation::   documentation's author
#@todo::            to-do list (you can use rdoc syntax : *)
#@fixme::           bugs to solve
#Method's description
#@usage::    what this method is about to, how to use it
#@param::    type and description of a paramater is used in the method
#            specify if it's implicit (session or instance variables)
#@return::   type of the returned value and a description
#@todo::     to-do list
#@fixme::    bugs to solve

Strict conventions on documentation are a necessity today. It makes running automated systems on the code much easier, the lack of such a convention is a gaping hole in the Ruby On Rails arena. And no, the code is not the documentation, neither are Unit Tests.

What we tried was to get the minimal set of "tags" that are necessary for an API style documentation which makes writing the code in a distributed fashion much easier. While keeping in mind how important it is to stick to the existing so that we can re-use tools that are already there.

Now, we can start commenting soundly… hoping others will jump on the wagon and we can start working on a general solution.

blog comments powered by Disqus