How to keep code examples in javadocs up to date

Question

I'm working on a small library that provides implementations of basic, well known string metrics. Mostly for my own education. So development happens whenever I've got a bit of spare time.

Because of this I've automated most processes so I can release a version as often as I work on it without too much effort. However maintaining the Java doc is still a burden because it includes examples.

As the API evolves I manually have to check each example over and over again. Is there a better way to do this?

I have considered moving the documentation and examples into a separate project (e.g. Caliper Tutorial) so it can be re-factored and compiled along with the regular code. However that does move the documentation away from the class it is about.

So yeah. I'd like to have my cake and eat it too. :D

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

If the above it too abstract. This is a sample of documentation. Currently I'm adding static constructors as advised by Effective Java e.g. Tokenizers.createQGram(2) while depreciating the constructor method. Each time I do something like this, I'd have to update the example code above and check if it still works.

Answer 1

This might not answer your question - depending on how much of a 'requirement' it is to have these examples in your documentation.

Perhaps you could do a different angle: Provide examples in your JUnit tests. (Perhaps even a package like com.examples) The problem with code in comments is that your IDE is going to ignore it, for the most part. But your IDE will validate the code in your JUnit tests. By doing this, you ensure the code examples are 'correct' - the tests will either not compile or simply fail if you haven't updated them.

I'm not a wizard with Javadocs, but there might be a way to link your source file's documentation to the JUnit file with the example code in it. I really wouldn't know where to begin on this though. A cursory googling showed me the @see tag. I tested it in a project but haven't tested it in an actual javadoc after it was generated.

This would definitely require a bit of research up-front, but I really think you'd be better off in the long run if your code examples were actually being compiled.

As a stretch-goal, you could also add in code coverage when running your JUnit examples. This way you would know at-a-glance how much of your code base is covered by your examples.