What's Up, JavaDoc?

The Java documentation tool, javadoc, has been somewhat neglected in recent releases, but in JDK 7, it's been getting some amount of long-overdue TLC, albeit mostly under the covers.

Internally, the biggest change has been to rewrite much of the internals of the standard doclet with respect to the way it generates pages. Previously, javadoc worked by processing data structures modelling the API and then generating the HTML files with a combination of using strings and by writing directly to an output stream, which means you need to know sequentially everything that needs to be written. As anyone who has tried to do this knows, this is hard to get right, and in a number of places javadoc got it wrong, and as a result it generated invalid HTML.  Ooops.  Now, the doclet works by creating an HTML "document tree" using a family of internal, new HTMLTree classes. This allows pages to be created non-linearly when necessary, and allows the page to be written by simply walking the document tree. There's a special node that is used to provide user-provided HTML fragments, which may come from documentation comments or from command line options. For now, these fragments are not checked for validity, but given valid input, javadoc now generates valid compliant HTML as output.

As part of the work to make sure that javadoc generates valid HTML output, we have updated the output to meet the Section 508 accessibility guidelines as well. This has caused some minor changes in the visual appearance, such as ensuring tables have captions, headings, and so on.

Also as part of this work, we have updated javadoc to use CSS and a stylesheet. This means that it is reasonably easy to change the appearance of the generated documentation by simply replacing the stylesheet in the generated documentation.

There have been some other more subtle changes as well. javadoc used to be such that it could only be executed once in any VM. This was not a significant restriction as long as javadoc was run using the command line tool, which started a new VM for each invocation of javadoc, but it was a significant impediment for speeding up test execution in order to be able to test javadoc more, and more often. We have also started the work to convert javadoc to use the javax.tools Compiler API, although more work in this area is required.

What's Next?

Now that javadoc uses a better foundation to build and generate compliant HTML, we are much better placed going forward to consider more radical changes to the contents of the pages, including the possible use of JavaScript for search and menu operations.

Having turned our attention to the way javadoc writes its output, it's now time to also turn our attention to the way it reads its input. In order to be sure we are generating truly compliant (X)HTML, we need to be able to detect issues in any user-provided (X)HTML fragments, in documentation comments or options. One way to facilitate this will be to extend the com.sun.source Compiler Tree API to provide structured access to the content of documentation comments.

Finally, the com.sun.javadoc API has largely been superseded by the new javax.lang.model Language Model API, and so with new language features on the horizon that will require javadoc support, it may be appropriate to migrate the standard doclet onto the newer API.


Thanks to Bhavesh Patel for providing feedback on this entry, and for working on the features described here.

Comments:

It's nice to hear that the Javadoc system is getting an upgrade. Is there any chance of fixing this bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5101868

Posted by Ryan on June 02, 2011 at 04:46 AM PDT #

Many thanks for working on the javadoc tools! I was afraid that this tool was neglected. It would be nice to have search capabilities, showing/hiding static and protected members on demand, getters/setters show as single properties, categories, valid XHTML output...

Posted by Martin Desruisseaux on June 02, 2011 at 08:25 PM PDT #

Excelente.

Posted by leonardoavs on June 03, 2011 at 01:19 AM PDT #

Is there a chance that JavaDoc will maybe get even near to the level of usability of ScalaDoc?

Posted by steve on June 04, 2011 at 12:40 AM PDT #

JAVADOCs are the best form of api documentation I have ever used. If changes are made every page should still maintain a very consistent look and feel.

Posted by Colton on June 15, 2011 at 11:24 AM PDT #

Can you post a link to some of the example output by the new JavaDoc tool?

Posted by Jevon on June 16, 2011 at 12:30 AM PDT #

Has there been any discussion about removing the HTML frameset from generated javadocs?

Posted by Asaph on June 17, 2011 at 07:00 AM PDT #

Hi Jonathan,

Nice post - thanks. What do you mean by "test javadoc"?

Rob
:)

Posted by Robert Mark Bram on June 22, 2011 at 10:16 AM PDT #

Off topic:
Should the class name be HTMLTree or HtmlTree?
Compare with URLConnection or HttpServlet...

What's the preferred acronym capitalization in the JDK nowadays?

Posted by klr8 on June 23, 2011 at 04:14 PM PDT #

@Martin: most of the features you suggest are already on the radar. The one that wasn't is now. Disclaimer: being on the radar is no guarantee of future implementation.

Posted by Jon Gibbons on July 22, 2011 at 05:46 AM PDT #

The new Javadoc looks nice, but I find the method summary less readable than the original version. I would suggest the following changes to improve the appearance:

http://people.apache.org/~ebourg/java7doc-fix.css

For those using GreaseMonkey here is a script to apply these changes automatically when visiting the Java 7 API on the Oracle site:

http://userscripts.org/scripts/show/108797

Posted by guest on August 01, 2011 at 08:01 PM PDT #

Post a Comment:
Comments are closed for this entry.
About

Discussions about technical life in my part of the OpenJDK world.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today