Putting Code in JavaDoc

A couple of Ant tasks let you embed both code and sample output in your Javadoc.

Following my post about how we include code fragments in our books, Marty Lamb told me about an interesting thing he does to include sample output in code documentation. I thought I’d share it (with his permission).

Your "Putting Code in Books" post the other day caught my eye, as I’ve struggled with a similar issue in the past: Putting Code in API Documentation.

Along with code, I also needed a way to include its corresponding output in the documentation. My API came with quite a bit of sample code and I dreaded the thought of manually keeping the documentation and examples in sync. (There was a time when the API in question was much more active, and the samples changed frequently.)

I developed two Ant tasks to help me out with this. The first, called "snip", extracts portions of source files and stores them in System properties for use by other Ant components (such as copy filters). This allows me to simply insert placeholders into the documentation. The placeholders are replaced with current source code when the documentation is generated.

The second task, called "rundoc", processes a source text file, finds substrings matching a specific pattern (@@rundoc:COMMAND@@), executes the specified COMMAND, and replaces the substring with COMMAND’s output. The current version formats the replacement text using docbook <prompt> and <computeroutput> tags, but could be trivially modified to output a different format.

Both are open source under a BSD license. Neither is terribly sophisticated and they would be easy to reimplement for other build tools. They can be downloaded from www.martiansoftware.com/lab.

I haven’t tried this software, but it sounds interesting.