Pluggable reflection's benefits

By applying javadoc to files and reflectdoc to reflection, you can compare the HTML outputs to reveal unexpected differences. By applying reflectdoc to system classes, moreover, you may produce documentation that is not included in the standard distribution. For example, Figure  is a portion of the JDK 1.2 documentation for java.lang.reflect.Method. Figure  is the HTML documentation generated by running our reflective version of javadoc, specifically reflectdoc java.lang.reflect.Method.

You might appreciate reflectdoc just for presenting reflective information in the familiar format of javadoc. But note the slight differences. Comments appear in Figure  but not in Figure . The class modifier synchronized appears⁵in Figure  but not Figure . The same is true of URL links, because reflectdoc was run only on java.lang.reflect.Method. Future work may include developing activedoc for producing and controlling javadoc's output dynamically.

reflectdoc reveals the following undocumented information about class Method:

• Private instance variables: The Method class has the variables listed in Figure . In the JDK documentation, the Variables section does not exist.

• A private constructor: Method has the private default constructor shown in Figure .

• A static copy method whose signature is shown in Figure .

Figure: Variable Index

Figure: Constructor Index

Figure: Copy method

Knowledge of private and undocumented features might not be crucial, but it can offer insight into the software's design. And you never know what you might find unless you look. Judging from the API, one might expect class Class to have properties like name, superclass, interfaces, and so forth in its implementation. But one might also expect Class's implementation to be lightweight. reflectdoc reports that class Class has no member variables at all, thus confirming the latter expectation.

Often, information is deliberately omitted in documentation produced by javadoc (e.g., private members are not displayed), since these are not part of the interface. But whether certain implementation details should be hidden is orthogonal to whether you have access to the information. The synchronized modifier bug is an example where even reflective information may be wrong [33].