Adopt Javadoc

Version 1

         Adopt Javadoc

         Improving Javadoc is part of the AdoptOpenJDK Program.

         Goals and Ideas

         Javadoc is a great standalone part of the OpenJDK that could do with some love. The following broad areas have been identified as requiring some love.

         The London Java Community has put together a team to tackle aspects of this. Items bolded are currently being worked on.

    • Search
    • In-place expansion of a method definition when clicking on it to see more detail
    • Links to the source code from the API documentation.
    • Use upcoming new DocTree API from langtools group
    • Reorder/regroup class members by static/instance
    • Use JavaScript menus to help navigate within page (issue here is o/s Javascript libs)
    • Interactive JavaDoc viewer, available as some combination of standalone application, applet, or webstart app
    • Lightweight way to validate javadoc comments (idea here is to use DocTree API and write a plugin for javac to validate HTML in comments)
    • User-pluggable stylesheets
    • New tags (e.g. from JSR 260?)
    • categorisation of methods and fields by their target use
    • semantical index of classes and packages
    • distinction of static, factory, deprecated methods from ordinary methods
    • distinction of property accessors from ordinary methods
    • combining and splitting information into views
    • embedding of examples, common use-cases along with Javadoc
    • Move away from use of frames to HTML 5 with tabbed interface for
    • multiple pages to be displayed at once.
    • Dynamically display inherited features in-line

     

         Setup

         Before you setup in any any IDE, you need to checkout the langtools hg repository.


         Setup in Eclipse

    1. Create a new eclipse project
    2. Add the langtools/src/share/classes folder from your openjdk install as a source folder.
    3. If you get errors about rt.jar then remove your JRE System Library from the buildpath. You then need to go 'Build Path', 'Add Library' and re-add your JRE System Library. These errors will now disappear.

         NB: before you commit any patches, make sure that you use the openjdk style guides.


         Setup in Netbeans

         There is an existing netbeans project in the "langtools/make/netbeans/langtools/" directory of openjdk that can be opened.


         Commandline Ant

    1. cd langtools/make
    2. ant -Dboot.java.home=$ALT_BOOTDIR

         NB: replace $ALT_BOOTDIR with an existing JDK 7 installation.


         Source Code Overview

         Here are some notes about the Javadoc source code:

    • The classes that implement the HTML generation part of javadoc are all in the com.sun.tools.doclets.formats.html package.
    • The entry point to this part of the codebase goes via SourceToHTMLConverter.
    • The low level HTML generation API is located in com.sun.tools.doclets.formats.html.markup - so its better than just stringbuffer concatenation.
    • The API traverses an object graph representing the Java Source code. These objects are a combination of the standard compiler API and javadoc specific objects.
    • The Javadoc specific objects are implementations of com.sun.javadoc.Doc and its associated hierachy.