TCKs for the Java platforms
Diving into that kind of topics always is a good candidate to polarize the development community. Especially because documentation is still a topic which tends to be forgotten or delayed completely. To me documentation is key on may levels. On a framework level it assures that your users don't struggle and you lay a good ground for quick adoption. To me the Arquillian project and team did an amazing job in their first years. Even on a project level this makes sense to quickly swap new team members in and out without losing knowledge. But there is another area which not simply benefits from it but has a strong relation to documentation: The Java TCKs. All Java Platforms define Java Specification Requests (JSRs) as the point for language improvements. A Technology Compatibility Kit (TCK) is a suite of tests that at least nominally checks a particular alleged implementation of a Java Specification Request (JSR) for compliance. Given the fact, that most specifications exist in some Office like documents and are pushed around as PDFs for review and comments it is nearly impossible to say weather a TCK has a defined coverage of the original specification at all. This at best is scary. Most of the time it is annoying because Reference Implementations (RIs) simply forget to cover parts of the spec and the user has to handle the resulting bugs or behaviors in specific ways. If that is possible at all.
Just a short note here regarding the availability of TCKs. Most of them aren't available as of today but subject to terms of license and financial agreements. Hopefully this is going to change with the upcoming changes to the Java Community Process.
Some JBoss Goddess to cure documentation
It all begins with the specification. This is a xml document which defines the different sections and required assertions.
<specification>
<section id="1" title="Chapter 1 - Introduction"/>
<section id ="2" title="Chapter 2 - What's new">
<assertion id="a">
<text>A simple sample test</text>
</assertion>
</section>
</specification>This document is the base line for your tests. You now need to go ahead and equip all your tests with relevant section and assertion information. This might look like the following:
SpecVersion(spec = "spectests", version = "1.0.0")
public class AppTest {
@Test
@SpecAssertion(section = "2", id = "a")
public void simpleTestForAssertion() {
App app = new App();
assertEquals(app.sayHello("Markus"), "Hello Markus");
}
Combined with a bit of maven magic (maven-processor-plugin) all the annotations are parsed and a nice report is generated about the overall coverage.If you want to have a look at the complete bootstrap example find it on github.com/myfear.
The Hard Parts
This obviously is a no-brainer. To add some annotations to your tests will not be the hardest thing you ever did. What is really hard is to convert your documentation into that fancy audit xml format. There are plenty of ways to do this. Given the fact, that most of the companies leading a JSR have some kind of hard-core document management in place should make this a once in a lifetime thing to implement. If you're working with Microsoft Word you could also use the available xml schema to write well formed documents with it (which is a pain! Don't do it!).
Plenty of Ideas
The little utility classes work comparably well. But there is still plenty of room for improvements. It might be a valid idea to have some supportive information here like issue-numbers or other references. I also would like to be able to use asciidoc in the documentation :) But I'm not complaining here because I am not going to change it myself. But if anybody is interested, the complete thing is on github.com and I believe those guys know how community works and accept contributions.
Future Wishes for the JCP
Given that simple and easy approach it would be a good thing to foster adoption along with JSRs. So if you like it approach the EC member you trust and make him/her aware of this and put it as an idea on their list.
