JEP 105: DocTree API: implementation preview (original) (raw)

Jonathan Gibbons jonathan.gibbons at oracle.com
Wed Sep 19 22:39:01 PDT 2012

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 ) and end tags (like ) 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

More information about the compiler-dev mailing list