// Internet Duct Tape

Searching for the Perfect Inline Code Documentation Tool

Posted in Programming Tools, Ruby, Technology, Writing Better Documentation by engtech on March 07, 2008

Programming Tips

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.

engtech-documentation-unravelling.png

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.

Related Posts

12 Responses

Subscribe to comments with RSS.

  1. engtech said, on March 07, 2008 at 7:49 pm

    holy crap Google is fast. I go to do some more research on this subject 20 minutes after writing a blog post and I’m already #4 for those terms.

  2. Lord Byron said, on March 07, 2008 at 10:34 pm

    Your blog is getting far too technical for me. What happened to the good old life hacks stuff?

  3. Andrew said, on March 07, 2008 at 11:23 pm

    engtech: master of the enticing post title :)

  4. Barbara Ling said, on March 08, 2008 at 7:23 am

    Wow, what memories your post brought back! Long long ago, back when “java” meant “coffee”, I used:

    SCCS!
    Sable!
    Sablime!

    for source code control/documentation. It’s nice to see how technology has improved over the past few decades or so…

    Now, if you could give me some troff and Framebreaker and Innergrief, I’d be in heaven. :)

    Enjoy,

    Barbara

  5. Pete said, on March 08, 2008 at 7:56 am

    Doctools in Python is superb. Partly because it has language support (docstrings, etc) and partly because of ‘doctests’.

    Basically you can put simple unit tests in the inline docs and then extract and run them. In the docs they look just like usage examples, so it effectively keeps your documentation and actual code synchronised.

    They do use reStructuredText rather than Textile/Markdown, but it’s worth pointing out that rst predates the other two (I believe) and that Markdown is actually partly based on it (headings, emphasis, etc are identical). It’s also more suitable for generating non-HTML forms such as LaTeX.

  6. [...] // Internet Duct Tape blogging / programming / technology / lifehacks Skip to content Subscription OptionsMost Popular PostsIDT Labs – Free Software ToolsWordPress.com Resources – Tips, Tricks and ToolsWordpress.com Theme ReviewsWordpress.com Theme Review HelpGreasemonkey script: WordPress Category ResizerWordpress.com 7 Day Referrer ParserPerl Script – WordPress.com 7 Day Referrer ParserGreasemonkey Script: Akismet Auntie Spam for WordpressGreasemonkey Script: Find images that are too wideTag Cloud Generator for Wordpress.comTag Cloud Generator AdvancedTag Cloud Generator – Release NotesWordPress Themes by InternetDuctTape.comBlack and Blue and Read All Over Theme for WordPress SandboxMoon Under Uranus Theme for WordPress SandboxMiscellanious WordPress Scripts and ToolsGreaseMonkey Script: WordPress Comment NinjaTechnorati Favorite Your FansTechnorati Favorite Your Fans – Release NotesComic BloggerGreasemonkey script: Flickr always search for Creative Commons licensed photosGreasemonkey Script: Yahoo Pipe CleanerTag CloudAll Posts by Category and TitleSeriesGift Guide for Geekseaster eggsReader Appreciation for RSS subscribersWelcome to Internet Duct Tapegoogle1ec000b3808eedbf.htmlAbout MeDisclosureImage Credits « Searching for the Perfect Inline Code Documentation Tool [...]

  7. Sandy said, on March 11, 2008 at 6:37 pm

    2Engtech,
    sometimes your post after 20 min can be 1st in google SERP :)

  8. [...] Searching for the Perfect Inline Code Documentation Tool 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. [...]

  9. Rainey said, on June 21, 2008 at 11:12 pm

    I am new to programming and never learned how to document code. Can anyone point me to a good book where I can learn good documentation practices?

  10. Al Gonzalez said, on July 02, 2008 at 1:46 pm

    Have you look into Natural Docs http://www.naturaldocs.org/

  11. JeromeH said, on September 12, 2008 at 3:52 am

    What would be needed in 2008 is a doxygen like tool that generates HTML documentation you can edit Wiki style. Then reinsert documentation in code if wanted.

    Round-trip documentation actually!

  12. saks said, on September 29, 2008 at 11:13 am

    I think it would be useful : Ruby Documenting Tool released
    The Ruby Documenting Tool application enables you to view, edit and
    write comments in ruby source files in more convenient way.. The Ruby
    Documenting Tool follows Freedesktop.org and GNOME standards to provide
    integration with Desktop Environment.
    http://rubyforge.org/projects/rudoto/


Comments are closed.

Follow

Get every new post delivered to your Inbox.

Join 280 other followers

%d bloggers like this: