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
appears5in 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:
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].