Documentation Enhancer for Java

Overview

Requirements

Download

FAQs

Forum

Reviews

Update: February 2, 2005

What is Documentation Enhancer for Java^TM?

Documentation Enhancer for Java^TM is a framework that enhances Javadoc files by enriching them with new information. The information is gathered by statically analyzing the corresponding Java class files. This technology is designed as a configurable framework, which allows the developer to change the way the new Javadocs are generated, add new kinds of information, and more. The framework already contains enhancements in the following three aspects: semantic information, sorting, and navigability.

Semantic information: By inspecting and analyzing method bodies, the Documentation Enhancer adds information about the behavior of classes to their Javadocs. This information is based on the method implementations, which means that the product breaks Javadoc's philosophy of providing information based on class and method signatures only.

The semantic information added by the Documentation Enhancer does not depend on user comments, and in some cases can be more accurate. 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", an order that puts key classes first, and can help you better understand the class library at hand.

Navigability: The entire set of information added by the Documentation Enhancer is cross-linked in Javadoc manner, and therefore allows for easy navigation between related Java constructs, often revealing new connections and relations.

The Documentation Enhancer provides the following semantic information:

• Call-graph information: for every method, what other methods may call it and what are the methods that it may 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.

How does it work?

1. Information from the original Javadoc files is processed.
2. Static analyses are performed on classfiles.
3. Transformers are applied on the information generated in stages 1 and 2, re-creating the Javadoc look-and-feel with the analysis results added.

The current release includes a set of analyses and presents them in a particular predefined way, but the underlying architecture is an extendible framework. The framework supports simple addition of other analyses results and visualizations. Please refer to the framework.html documentation shipped with the tool if you are interested in extending the tool.