Java in a Nutshell, 5th Edition

How the Quick Reference Is Generated

For the curious reader, this section explains a bit about how the quick reference material in Java in a Nutshell and related books is created.

As Java has evolved, so has my system for generating Java quick reference material. The current system is part of a larger commercial documentation browser system I’m developing (visit http://www.davidflanagan.com/Jude for more information about it). The program works in two passes: the first pass collects and organizes the API information, and the second pass outputs that information in the form of quick reference chapters.

The first pass begins by reading the class files for all of the classes and interfaces to be documented. Almost all of the API information in the quick reference is available in these class files. The notable exception is the names of method arguments, which are not stored in class files. These argument names are obtained by parsing the Java source file for each class and interface. Where source files are not available, I obtain method argument names by parsing the API documentation generated by javadoc. The parsers I use to extract API information from the source files and javadoc files are created using the Antlr parser generator developed by Terence Parr. (See http://www.antlr.org for details on this very powerful programming tool.)

Once the API information has been obtained by reading class files, source files, and javadoc files, the program spends some time sorting and cross-referencing ...