Disparities

The doclet repository that javadoc uses internally resembles reflection in at least two respects:

• The repository is not persistent: its lifetime is limited to that of the hosting javadoc's execution. The repository lives and dies with each such execution, just as reflective information is available only at run-time.

• The Doclet API and the Core Reflection API are nearly isomorphic. The Doclet API classes ClassDoc, MemberDoc, FieldDoc, ConstructorDoc, and MethodDoc correspond to the Core Reflection API classes Class, Member, Field, Constructor, and Method. The methods correspond closely as well, although they are distributed a little differently in the two class hierarchies.

Although quite similar, the two APIs are incompatible. The JDK design fails to recognize this similarity, let alone providing the pluggable abstraction and attempting to unify them. As a result, things tend to be more complex than they need to be, and reuse opportunities are forgone. Here are two examples of difficulties in the design, the first seen from its designer's viewpoint and the second from a client's:

1. The Doclet API's design is newer and more complete than the reflection API's. But since no connection between the two was made, the improvements have not and may never make their way into the reflection API.

2. If you already have SomeReflectionTool that adheres to the Core Reflection API, you cannot reuse it with javadoc; you must rewrite it as SomeDocletTool. The opposite is also true: an existing SomeDocletTool cannot be easily applied to reflective information.

   In particular, the sun.tools.javadoc.doclet.Standard HTML doclet, which javadoc itself uses by default, cannot be retargeted to .class files. Even newly written programs (like your SomeDocletTool) cannot use reflection unaltered--a common interface does not exist. There is no way to replace the front-end analyzer. There isn't even a converter in the form of a ClassDoc constructor that would translate reflection information into doclets.

Pluggability would let us disconnect javadoc from its repository source, namely doclets, and plug it into reflection.