Next: Pluggability
Up: A Retargetable javadoc
Previous: A Retargetable javadoc
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:
- 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.
- 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.
Next: Pluggability
Up: A Retargetable javadoc
Previous: A Retargetable javadoc
David H. Lorenz
2003-02-17