Annotated Source Code As Documentation, With Docco

With the first bits of my Backbone.Marionette plugin being available on Github now, I wanted to try out the Backbone-style of annotated source code as documentation. I like the way Backbone has this set up, and I often refer to it when I want to know how something works internally, or find a specific piece of code to copy.

You can find the annotated code for Backbone.Marionette here.

Note that this only part of the documentation solution for a project, though. If you expect to annotate your source code and call your documentation done, you’re a scumbag oss coder:

ScumbagCoder

That being said… commenting your code is a great way to provide additional documentation. It will help people understand the code they are reading, and help them write better code using your library or framework.

Docco

To generate the annotated document for Backbone.Marionette, I used Jeremy Ashkenas’ “Docco” tool – the same one he uses to generate Backbone’s annotated source code. The great thing about this project site: it’s build using the Docco tool. :)

There are a number of different ports for this tool available, so you can run it in NodeJS, Ruby, Python, .NET and more. I decided to use the NodeJS version that Jeremy built, mostly because I’m always looking for an excuse to use NodeJS tools. The process of getting this up and running was surprisingly simple, though it did involve a few steps and a bit of guess work on my part. Hopefully this blog post will help others get around the guess work.

The Source Code

If you read through the source code for Backbone.Marionette, you’ll find a bunch of standard // comments throughout the code. This is pretty normal stuff, for the most part. I’ve added some comments above my objects and methods, to help explain what they are and how to call them.

The only significant difference between a normal command and a Docco ready comment is that some of the comments have a //————— line underneath of them. This tells Docco that this is going to be a section header, in the compiled documentation. Using a fixed with font, set the number of – in that comment line to the same width as your header title:

// This Is A Header
// ----------------


// This is a normal comment, that will become part of the
// annotations after running through the Docco tool. Use this
// space to describe the function or other code just below 
// this comment. For example: 
//
// The `DoSomething` method does something! It doesn't take any
// parameters... it just does something.

function DoSomething(){
  // and by the way, this will show up
  // in the docco file, too. :)
  alert("I'm doing something!");
}

Other than that, comment your code as you normally would. You can also do some cool tricks like using `bacticks` around code, and the generated document will encompass that inside of a <code> tag, with CSS set accordingly. There’s likely some other tricks you can do, too, as this is all run through a Markdown processor to build the docs.

Side note: if you haven’t learned Markdown yet, do yourself a favor and learn it. It’s becoming the ubiquitous documentation and code commenting style around the development community. I think this is largely due to Github supporting it and encouraging it’s use in readme files and Github wiki pages. I’m at the point where I take notes in Markdown, when attending technical sessions or taking notes from conversations.

Docco Prerequisites

There are a few things you’ll need to install if you want to use the NodeJS version of Docco:

  • NodeJS
  • NPM (Node Package Manager)
  • CoffeeScript
  • Python
  • Pygments

If you’re on a Windows machine, you can find installation instructions for NodeJS, NPM and Python around the web fairly easily. Here’s the instructions for OSX:

NodeJS (via Homebrew):

sudo brew install node

NPM:

sudo curl http://npmjs.org/install.sh | sh

CoffeeScript:

sudo npm install -g coffee-script

Python:

May be included in OSX… might be part of XCode. I’m on OSX Lion and I have the latest XCode. I didn’t need to install anything for Python to be available to me. Python is needed for the “easy_install” tool, which is Python’s package manager (similar to NPM or RubyGems).

Pygments:

sudo easy_install pygments

sudo npm install -g pygments

I’m not actually sure if you need to install the NPM pygments… I did, and things worked well for me. I’m assuming this is needed so NodeJS can run the Pygments tool.

Installing Docco

Once you have all the prerequisites in place, installing Docco is a one liner:

sudo npm install -g docco

Now you have access to the `docco` command line tool.

Running Docco On Your Code

This is super easy. Just run `docco {file pattern}` from the command line. For example, the above `comments.js` file can be run like this:

docco comments.js

You can also use file patterns such as `*.js`

Setting Up A Rake Task

I don’t like to run things manually when I don’t have to. Since my Marionette project uses Sinatra and Rake to run it’s Jasmine test suite, I decided to create a Docco task. Here’s what that would look like, for the above comments.js file:

desc "Build the Docco annotated source documentation"
task :docco do
  `docco comments.js`
end

Now I can run `rake docco` from the command line and it will build the docs for me. … yeah, this is probably overkill, but I wanted to do it anyways. :)

The Results

Here’s the results of running Docco against the above comments.js file (view it here, if you’re in an RSS reader):


Post Footer automatically generated by Add Post Footer Plugin for wordpress.

About Derick Bailey

Derick Bailey is an entrepreneur, problem solver (and creator? :P ), software developer, screecaster, writer, blogger, speaker and technology leader in central Texas (north of Austin). He runs SignalLeaf.com - the amazingly awesome podcast audio hosting service that everyone should be using, and WatchMeCode.net where he throws down the JavaScript gauntlets to get you up to speed. He has been a professional software developer since the late 90's, and has been writing code since the late 80's. Find me on twitter: @derickbailey, @mutedsolutions, @backbonejsclass Find me on the web: SignalLeaf, WatchMeCode, Kendo UI blog, MarionetteJS, My Github profile, On Google+.
This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Jonathan Mahoney

    I’ve been recently dabbling with Docco and can say that its a fantastic addition to a project. I would recommend that, if you’re uncomfortable with the CoffeeScript implementation that you check out the various ports into other languages.

    Our team use C# primarily, and as such are more comfortable using the C# implementation of Docco, called Nocco. This and others such as Pycco and Rocco are all mentioned in the intro paragraph on Docco’s site:  http://jashkenas.github.com/docco/

  • http://twitter.com/mrpollo Ramon Roche

    I dont think hombrew lets you do sudo anymore

    • http://mutedsolutions.com Derick Bailey

      i might be on an old version, or maybe i installed node a month or two ago, so i was just going off memory for that :)

  • http://truewill.myopenid.com/ Bill Sorensen

    THANK you! It’s nice to hear from someone else who’s felt the pain of poorly-documented open source projects.

  • Anonymous

    thanks so much for this! i’m a novice web developer who’s been tasked to develop api options for the company i’m interning at. a simple yet highly helpful blog post.

  • Tony

    can you make a blog post or page with a list of JS projects covered in docco format? I am finding them great resources for studying patterns.

    keep chugging.
    tony

  • Paul Tiseo

    Curious to know if you still use docco? If not, what is your current workflow(s) for generating marionette docs?

    • http://mutedsolutions.com Derick Bailey

      for annotated source code, docco is still the way to go. for the real documentation, though, it’s all hand-written in markdown files, stored in the github repo w/ the code

      • http://www.arrogantgamer.com/ arrogant.gamer

        Docco is still pretty sweet, but I’m sad that it can’t handle projects out of the box. None of the other options I’ve tried (docco-husky and groc) were nearly as nice.