IBM®
Skip to main content
    Israel [change]    Terms of use
  
 
 
    Home    Products    Services & solutions    Support & downloads    My account    
IBM Research

eJavaDoc: Documentation Enhancer for Java

Software Asset Management


Overview


  1. Overview
  2. How Does It Work?
  3. Downloading and Installing Documentation Enhancer for Java
  4. System Requirements
  5. Documentation
  6. Examples
  7. Status
  8. Credits


Overview

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 class files. The tool enhances three aspects of Javadoc HTMLs:
  1. Semantic information
  2. Sorting
  3. 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 user comments and class/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.

How Does It Work?

Documentation Enhancer for Java's operation can be divided into three phases:
  1. Information from the original Javadoc files is processed and stored in XML files.
  2. Static analyses are performed on classfiles and the results are stored in XML files.
  3. XSL transformations are applied on the XMLs generated in stages 1 and 2, re-creating the Javadoc look-and-feel with the analysis results added.

Downloading and Installing Documentation Enhancer for Java

Documentation Enhancer for Java can be downloaded from IBM's AlphaWorks website. Click here for a direct download.

To install Documentation Enhancer for Java, simply unzip the file in the desired destination directory. Documentation Enhancer for Java does not change any system configuration or registry value, and can be uninstsalled by simply removing the files. Enhanced documentation files can still be used after Documentation Enhancer for Java is removed from the system.

System Requirements

System requirements for enhancing documentation files:
  • Java 2 SDK 1.3 or later (tested under Microsoft Windows XP and Windows 2000 only).
  • Large amounts of RAM (256MB or more) are highly recommended for enhancing large components.

System requirements for viewing the enhanced documentation files include Microsoft Internet Explorer 5 or later, or any updated web browser.

Documentation

  1. A Guide to the Information Added by eJavaDoc
  2. Readme file (from the program's distribution)
  3. FAQ

Examples

Two example sets are available online (in zip files):
  1. Enhanced CFParse Documentation. CFParse is a low-level API for interactive classfile editing. (The CFParse homepage is on IBM's AlphaWorks website.)
  2. Enhanced Struts Documentation. Struts is an open-source framework for building web applications. (The Struts homepage is on the Apache Jakarta website.)

Status

Although the current release uses a closed set of analyses and presents them in a particular predefined way, the underlying architecture is an extendible framework. The framework supports simple addition of other analyses, results, and visualizations. Please contact the authors if you interested in extending the tool.

Credits

Documentation Enhancer for Java was developed by Eran Belinsky, Tal Cohen, Vitaly Feldman, and Sara Porat.

The tool is maintained by Neta Aizenbud-Reshef and Avi Yaeli.


































 
 

    About IBM    Privacy    Contact