Writing new retargetable reflective tools

To complete the javadoc example, we describe a prototyped version of javadoc that generates HTML documentation from reflective information, and in Section  we demonstrate its usefulness by comparing its output to the official JDK documentation for the Java Core Reflection API.

We have two alternative approaches to implementing a reflective version of javadoc. The first (re)uses doclets; the second does not. The reader is encouraged to use Figure  as a guide to the examples in particular and more generally to the difficulties conventional reflection creates and the benefits of pluggability.

Suppose we'd like to make javadoc generate HTML documentation using reflection. One tack is to implement a converter from instances of reflection classes to instances of doclet classes (represented by the downward arrows marked ``convert" in the figure). It is possible then to implement a classdoc tool that works much like javadoc except that it documents classes based on reflective information. Unlike javadoc, which works only on .java files, classdoc may work on .class files, hence its name.

A possible implementation strategy has the tool traversing the reflected information, building a temporary doclet structure, and then passing its root (necessarily of type sun.tools.javadoc.doclet.Root) to Standard.start(Root root)³ to generate HTML. Of course, not all doclet information can be constructed from reflective information. Some entries (e.g., comments) must be left empty or assigned default values. This could make the generated documentation look awkward. Avoiding that requires a different implementation approach, one independent of javadoc and the doclet package--a tool that generates the HTML output directly. reflectdoc is such a tool. Yet another implementation strategy would be to develop a bytedoc for parsing the .class files directly without using reflection (see Figure ).

Figure: JDK documentation for Method

Figure: Method documentation obtained via reflectdoc

AspectJ, an implementation of AOP for Java, recently provided a javadoc-like tool named ajdoc [19]. Running ajdoc SomeAspect.java generates documentation for the aspect SomeAspect, which includes aspect instance specifications such as issingleton, aspectual links to known advisors and advisees, advice summary, and more.

ajdoc is an application that uses this pluggability approach, and it is superior in design to javadoc. Akin to the -doclet option of javadoc, which generates output via an alternate doclet, Palm [27] added a -compiler option for generating a RootDoc instance via an alternate compiler.⁴Thus the user of ajdoc can control both the front-end and the back-end of the compilation. With a supplemental RootDocMakerImpl and a minor change to org.aspectj.tools.ajdoc.Ajdoc.java, one can build the doclets from .class files. For example, running ajdoc -standard -compiler RootDocMakerImpl java.lang.reflect.Method would produce documentation for Method via reflection. Nevertheless, AspectJ code cannot expect to reflect on aspectual structure but must make do with the underlying object structure. For example, running ajdoc -compiler RootDocMakerImpl SomeAspect generates documentation using reflection, but the result reveals SomeAspect to be a class, complete with instrumentation details, instead of displaying the aspectual information.