The Goldfish Chronicles

Something I’m increasingly trying to do in the Commons Lang code is to copy any examples from the javadoc into the junit tests. It’s embaressing when one of them is wrong

It’d be nice if I didn’t have to copy them (and have them get out of sync). Something xdoclet’y perhaps?

I guess a simple solution would be to pull the example code out into a separate tree of examples; hook the tests up so they run the examples as well as their own harder tests, and then have the javadoc have a url to the example.

Slightly better would be if we could plug a tiny bit of code into the javadoc doclet to let us add a new javadoc tag that would inline a block from the example. Something like @example org/apache/commons/lang/StringUtilsExample.java#foo

and in the example it would be something like:

public class StringUtilsExample {
   ... various bits of code ....
   //#foo
   piece.of.example.code();
   //#/foo
}

This entry was posted on Tuesday, February 1st, 2005 at 9:31 pm and is filed under Tech. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.