Lemma for documentation
ALR,
As you and the ShrinkWrap community begin to shift your focus to documentation, I'd like to recommend a tool named Lemma [1], developed by Christian Bauer, that falls right into your cup of tea. Lemma turns software documentation inside out by making the example code the first class construct and JavaDoc the surrounding prose. When combined with Arquillian, you can setup any code snippet imaginable in a test case and then wrap the documentation around it using JavaDoc. From there, you can insert the snippet + documentation into a master document, which itself is written in HTML.
Lemma likely falls under the category of executable reference documentation.
Here's an example. Consider a method from which you would like to select lines to be included in the documentation:
/**
* <p>
* To use the class, first instantiate it, then call either {@code getMessage()} to retrieve
* the message string or {@code sayHello()} to print the message to {@code System.out}:
* </p>
*
* <a
href="javacode://example.helloworld.HelloWorldTest#testHelloWorld()"
style="include: HELLOWORLD_USAGE;"/>
*
* <p>
* If you don't want the message printed to {@code System.out}, don't call the
* {@code sayHello()} method.
* </p>
*/
@Test
public void testHelloWorld() {
HelloWorld hw = new HelloWorld(); // DOC: HELLOWORLD_USAGE
assert hw.getMessage().equals("Hello World!");
assert hw.getMessage().endsWith("!");
hw.sayHello(); // DOC: HELLOWORLD_USAGE
}
This translates into the following reference documentation excerpt:
To use the class, first instantiate it, then call either getMessage() to retrieve the message string or sayHello() to print the message to System.out:HelloWorld hw = new HelloWorld(); assert hw.getMessage().equals("Hello World!"); assert hw.getMessage().endsWith("!"); hw.sayHello();If you don't want the message printed to System.out, don't call the sayHello() method.
I've played around with it some and confirmed that it works. There is plenty that could still be done to make it easier to use. I'd also like it be able to generate docbook instead of just HTML. Then, we could use it for isolated sections of the reference documentation.