Searching for the Perfect Inline Code Documentation Tool
Even amongst programmers I’m weird because I have an intense love for documentation. No, that doesn’t mean I overly comment my code, or that you’ll catch me browsing happily through the product requirements document during my coffee break. I should be more specific.
I have an intense love automatic documentation generation. Nothing makes me more tickled pink than seeing code and documentation living side by side in perfect harmony. I hate seeing documentation put on the company intranet only to diverge from the code it’s supposed to explain as the days go past. I hate hitting my head against a brick wall as I’m pouring through the source code trying to understand an API because at no point does it mention that it’s documented in a Word doc in another directory.
This is my rule of programming: documentation should live beside the code it documents, in the comments, especially if it’s API documentation. If your language of choice doesn’t already have some kind of automatic code generation tool then you’re probably using the wrong language.
A year and some change ago I did some research on some language independent automatic documentation tools. I thought it was about time I update that list with some of the tools I’ve played with since then.
Documentation Tools I’ve Known and Loved
RDoc – ruby documentation generator
It’s a great little tool for documenting the API for Ruby code. It’s what they use for the Ruby on Rails API documentation. It’s very concise and the wiki-like syntax is easily readable in the ASCII comments it’s generated off of. Here’s an example of a file with RDoc comments and the markup it generates. Ruby code only.
POD – plain old document generator
POD ships with Perl and has been around forever. It’s what they use for CPAN and perldoc documentation. Unfortunately it’s on the verbose side and it can overwhelm the code it is trying to document. Lists look absolutely horrible and unreadable in the ASCII comments with the =over, =item, =item, =back syntax. The bold and italic syntax definitely demonstrates that POD is from a time before HTML and Wikis became popular.
POD gives you some nice command line goodness though with pod2html, pod2text, pod2man, pod2latex, pod2fm and pod2usage. I particularly like pod2usage as a way of displaying command line options with –help.
But the real strength of POD is how you can mix documentation and code together by delimitating POD blocks and non-POD blocks. This means you can use POD in any language that supports multi-line comments!
DOXYGEN – document generator
Doxygen is a tool primarily intended for documenting C++ code (although I’ve gotten it to work with Python). The setup is more complicated than it needs to be if you’re trying to use it for something other than C++ document generation because you have to prefilter your source code to look like C++.
To Do: I want to get more familiar with Pydoc and Javadoc.
Building a Better Documentation Tool
I’ve never found a really good language agnostic code documentation tool. Which is surprising, because it should be trivial to write one. Here’s how I’d do it:
- Use some sort of 0-column =begin/=end sequence to indicate where documentation is.
- Comment character can be specified on the command line for languages that don’t support multi-line comments.
- Have default syntax use something like Markdown or Textile.
- DON’T INVENT YOUR OWN DOCUMENTATION FORMAT. It’s 2008 for !@$#’s sake. Use HTML or something more concise than HTML. If you’re an IT worker and you don’t know HTML then you’ve made your life a lot harder than it needs to be for no reason.
- Plugin engine to let people use their own syntax for writing “documentation” comments and translated to HTML.
- Use HTML, POD, Markdown, Haml, Markaby, or your wikisyntax with the right plugin.
- So long as it translates to HTML what else do you need? Again, it’s 2008 so you should be able to convert from html to text/man/latex/pdf/whatever.
- The only area that would need to be easier is creating cross-reference links.
- Good support for file hierarchies, but I shouldn’t need a configuration file to use it for simple structures.
Am I going to write it? Probably not, but I remain mystified that one doesn’t already exist. Lazyweb, let me know if I’m wrong.