JEP 105: DocTree API: implementation preview

[Jonathan Gibbons]

I have posted a preview of the API and implementation [1] of JEP 105: 
DocTree API [2].

This provides the ability to get a structured representation of a 
javadoc comment that can be used by tools to analyze the content of 
comments.

The API is a natural extension of the existing Compiler Tree API [3]. 
The new DocTrees utility class (com.sun.source.util.DocTrees) provides 
the ability to get a DocCommentTree for any declaration, given its 
TreePath. Each DocCommentTree node is the root of a hierarchy of DocTree 
nodes which can be processed by visitors in the obvious way. The 
hierarchy is based on the structure of the javadoc comment, consisting 
of plain text, entities, inline tags (like {@link Object}), and block 
tags (like @see Object). There are also nodes for HTML start tags (like 
<a href="#somewhere">) and end tags (like </a>) but there is no attempt 
to validate the general structure of any HTML fragments within the 
javadoc comment -- that would be the task of higher level software using 
the facilities of this API. A DocCommentTree can always be generated 
from any javadoc comment: any invalid input will be retained in an 
ErroneousTree node.

DocCommentTree nodes are generated lazily, if and when requested. There 
should be no performance or footprint impact on any tools not using the API.

DocTree nodes know their position within the source text in which they 
appear, and so any messages reported through DocTrees.printMessage can 
identify the the source and line on which the relevent DocTree node appears.

Finally, any valid reference to a Java package, class, method or field, 
as found within @see, {@link}, @throws, and so on, can be evaluated to 
get the corresponding Element. Unfortunately, the meaning of names as 
implemented by the existing javadoc tool is inconsistent with its spec, 
with JLS and even within itself. That all being said, the DocTree API 
has been written to mimic the existing behavior of the javadoc tool as 
much as possible, for now. However, now that we have better tools to 
analyze references within javadoc comments, and the ability to 
accurately locate those references, it would be good to minimize any 
differences as much as possible, which retaining compatibility with 
existing comments as much as possible.

-- Jon

[1] http://cr.openjdk.java.net/~jjg/7021614
[2] http://openjdk.java.net/jeps/105
[3] http://docs.oracle.com/javase/7/docs/jdk/api/javac/tree/index.html