javadoc TLC

The recent series of patches1 for javadoc completes the work started during JDK 7 to change the internal data model for standard javadoc doclets from strings to a document tree. As a result of this work, there should no longer be any unnecessary internal conversion from tree nodes to strings and back again.

As a side-effect of this work, some bugs were uncovered and fixed, such as not using entities for literal use of '<', '>', and '&', and conversely, treating some HTML fragments as plain text, and then incorrectly replacing those characters with entities. Oops. Also, the indentation of method signatures should now be fixed, so that parameters and exceptions thrown should be vertically aligned, as used to be the case.

A more important side-effect is that the code to generate HTML content has been consolidated within the com.sun.tools.doclets.formats.html package, leaving the main internal taglet API to be more format-neutral. This should make it easier to provide doclets that write to alternate formats.


1. hg: jdk8/tl/langtools: 17 new changesets
Comments:

Hi Jonathon,

Last November (2012) I created a simple proof-of-concept viewer for the Java SE7 API docs at
http://docs.oracle.com/javase/7/docs/api/overview-summary.html

The viewer is implemented as a javascript bookmarklet which runs on the NOFRAMES pages, and it implements something like an evolved frameset - using AJAX includes instead of frames, and with support for pushState-assisted-navigation.

You can watch an explanatory video at http://www.youtube.com/watch?v=fE3dgJRjczk

The viewer is *not* meant to be a demo of what Javadocs should look like - at a minimum I think some find-as-you-type functionality would be useful.

It *is* a demo of how one might unobtrusively implement - using AJAX and pushState - an enhanced viewer on top of the NOFRAMES sites that already get generated. Integrating a solution such as this into the generator would be quite straight-forward, imo.

Feel free to contact me for more details, explanation, better demo, etc.

Posted by Sean Hogan on July 22, 2013 at 09:18 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