[kepler-dev] Automatic Documentation Enhancement?

[Dan Higgins]

FYI,

http://www.alphaworks.ibm.com/tech/docenhancer


      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.


-- 
*******************************************************************
Dan Higgins                                  higgins at nceas.ucsb.edu
http://www.nceas.ucsb.edu/    Ph: 805-892-2531
National Center for Ecological Analysis and Synthesis (NCEAS) 
735 State Street - Room 205
Santa Barbara, CA 93195
*******************************************************************

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mercury.nceas.ucsb.edu/ecoinformatics/pipermail/kepler-dev/attachments/20050204/f2f11857/attachment.htm