|
|
 |
eJavaDoc: Documentation Enhancer for Java
Software Asset Management
|
- What is Documentation Enhancer for Java?
- Usage Scenarios
- The Analyses
- Running Documentation Enhancer for Java
- Running the Sample
- The Framework
What is Documentation Enhancer for Java?
Documentation Enhancer for Java is a tool that enhances Javadoc files by enriching them with new information. The information is gathered by statically analyzing the corresponding Java classfiles. The tool enhances three aspects of Javadoc HTMLs:
- Semantic information
- Sorting
- Navigability
Semantic information: By inspecting and analyzing method bodies, Documentation Enhancer for Java adds information about the behavior of classes to their Javadocs. This information is based on the method implementations, which means that Documentation Enhancer for Java breaks with Javadoc's philosophy of providing information based on class and method signatures only.
The semantic information added by Documentation Enhancer for Java does not depend on user comments, and in some cases it is more accurate because of that lack of dependence. User comments could be outdated, incorrect or even misleading. Information gathered from the implementation, on the other hand, is always accurate and exact.
Sorting: By default, Javadoc uses lexicographical sorting. Semantic information may serve as a basis for different sorting schemes. In enhanced Javadoc documentation files, you can choose "sorting by usage," which ranks key classes first. This can help you better understand the class library at hand.
Navigability: The entire set of information added by Documentation Enhancer for Java is cross-linked in Javadoc fashion. This allows for easy navigation between related Java constructs, often revealing new connections and relations.
Documentation Enhancer for Java provides the following semantic information:
- Callgraph information: For every method, what other methods may call it and what methods may it call. This analysis uses sophisticated type analysis algorithms to resolve virtual calls.
- Effect information: For every field, which methods may modify or inspect it. For every method, what may it do (modify, forward, inspect) to its parameters and to static fields, and what values it may return (if applicable).
- Reference information: For every class, which classes reference it and which classes does it reference. The same information is provided for packages at the package level.
- Executable classes: Classes that have a main(String[] args) method are detected and marked as such.
Reference information is used to sort the package and class lists, according to the number of incoming references. We believe that this sorting scheme can hint at the entry points for the analyzed component.
Usage Scenarios
Documentation Enhancer for Java was written with the following two scenarios in mind:
- A Java developer downloads a Java component from the Internet and wants to learn how to use it. In this typical scenario, the developer receives the JAR file containing the binaries (and any other binaries needed to use that JAR file) and the automatically-generated Javadoc documentation (other forms of documentation may also be available). However, this documentation is often insufficient, and perhaps even outdated. In this instance, the developer can use Documentation Enhancer for Java to produce richer and more accurate documentation.
- A library developer wants to make a product more accessible to users by bundling richer documentation with it. The developer generates the standard Javadoc documentation, and then enriches it with Documentation Enhancer for Java and distributes the rich documentation with the library.
The Analyses
The following analyses are performed by Documentation Enhancer for Java:
- Effect: Analyzes operations performed on method parameters and static fields. Provides description of values that can be returned from each method. Based on intra-procedural data-flow analysis.
- Callgraph: Models caller-callee relationships between methods. This graph is used for identifying all the method implementations within the component that may potentially be invoked at run-time, considering the polymorphic nature of Java method invocations.
- Reference graph: Models the static dependencies between classfiles.
- Miscellaneous: Detection of all classes that have a proper main method; detection of sealed packages in JAR files.
Running Documentation Enhancer for Java
Documentation Enhancer for Java is a command line tool. To run it, use the batch file Documentation Enhancer for Java that takes 3 or 4 arguments:
(Documentation Enhancer for Java javadoc-source output-folder source-path [dependent-path])
- javadoc-source: The root folder of the Javadoc HTML files tree. The file javadoc-source\index.html is the entry point to the documentation.
- output-folder: The root folder where you should place the enhanced Javadoc HTML files.
- source-path: Path to the binaries of the component (the classes which will be analyzed). If all the classes are included in a single JAR file or directory, just provide the file or directory's name. If a list of JAR files, ZIP files, and/or directories is provided, please use the Java classpath format (i.e., separate the items using a semicolon), and enclose the list in quotation marks.
- dependent-path: Path (in Java classpath form, enclosed in quotation marks) to all classes which are required for running the component. There is no need to include the files appearing in the source-path argument or rt.jar (the core Java SDK library).
If the analyzed component relies on external libraries, then the last argument is required for building callgraph. (Technically, only the direct/indirect super-classes/super-interfaces of the analyzed classfiles are necessary.) If any of these upward hierarchy classfiles is missing, Documentation Enhancer for Java prints the required list of classfiles and aborts.
Advanced users will notice that the batch file runs the Java interpreter with additional (hardcoded) parameters. These parameters set some particular configuration of our flexible framework.
When running, the tool may print error message and fail to convert some HTMLs. The main cause of failures are erroneous Javadoc HTML files. Errors in the Javadoc HTML files may result from programmers' incorrect addition of their own HTML tags to the Javadoc comments, which are used to generate the Javadoc files (consider, for example, the documentation of the method toString(double d) of class java.lang.Double in Sun's JDK 1.2.2). Besides that, incorrect parsing may result from version variations in Javadoc's output format, or simply (we hate to admit) from bugs in the application.
When the parsing of a Javadoc HTML file fails, the original (unenhanced) file is copied unchanged to the target location. The file failed_files in the destination folder contains the list of failed files.
Running the Sample
The sample given is a classfile parsing toolkit called CFParse (you can find out more about CFParse at IBM alphaWorks). Take a look at the batch file (sample.cmd) for running Documentation Enhancer for Java on this sample:
sample\input\cfparse\api sample\output\cfparse\api sample\input\cfparse\cfparse.jar sample\input\cfparse\jackie.jar
Its parameters are:
- sample\input\cfparse\api - the first argument is the location of the source Javadoc HTML files.
- sample\output\cfparse\api - the second argument is the location where we want the resulting enhanced Javadoc HTMLs to be placed.
- sample\input\cfparse\cfparse.jar - the path to the JAR file that contains the documented classfiles. It may contain other files (classfiles which are not documented, resources, etc.).
- sample\input\cfparse\jackie.jar - a library used by CFParse. As noted above, libraries used by the analyzed component are required for a complete analysis.
Run the sample by typing "sample" on the command line.
After the sample has completed (it may take some time, depending on your system's speed and amount of free RAM), browse the folder samples\output\cfparse\api in which the output resides. Open the file index.html with Internet Explorer and browse through the enhanced Javadoc. For a detailed discussion of the enhancements and additions, click here.
The Framework
Documentation Enhancer for Java is designed as a configurable framework, which allows you to change the way new Javadocs are generated, adds new kinds of information, and more. However, the framework is not yet documented. Please contact the authors if you are interested in using it.
| |
|
|
