Wednesday, June 22, 2011

New Java SE 7 Javadoc API Documentation Appearance

In my last post, I briefly referenced the Jonathan Gibbons's post What's Up, JavaDoc? that describes some recent changes to Javadoc, including changes that allow a CSS stylesheet to be applied to the documentation. Mark Reinhold's post JDK 7: Are we there yet? talks about the changes to the Java SE 7 API default display style. In this post, I briefly look at this change.

The next two screen snapshots demonstrate the traditional default appearance of Javadoc documentation we have seen for years and then demonstrate the new default appearance.



This default style is not limited to the standard SDK API documentation. It is also used for generating custom Javadoc for other Java applications. The next screen snapshot shows Javadoc being invoked via Ant using JDK 7 build 146 (the build supporting the new styling). The example built in this case is the code from my post How I Learned to Stop Worrying and Love Java's Ternary Operator.


As the screen snapshot indicates, I did not do anything special to apply the new styling. However, the output is new (and I think improved) as shown in the next couple snapshots.



The generated Javadoc directory includes a file called stylesheet.css. This text file can be changed to easily change the appearance. The next screen snapshot shows how it looks when I change the .rowColor, .altColor, and the background-color of the body.


I'm not recommending the colors in the above screen snapshot; they're merely intended to demonstrate how easy it is to alter the presentation's appearance.


Conclusion

I like the new default styling and it comes "out of the box" with no new effort as of JDK 7 build 146. This is only a minor and largely cosmetic improvement, but it is nevertheless welcome.

2 comments:

João Assunção said...

I like it alot.
It (almost) makes me want to write more documentation.

JOKe said...

it has the "oracle" look and feel in mind.

Still I prefer the old plain one