Improving Javadoc is part of the AdoptOpenJDK Program.
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.
- 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
- 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
Before you setup in any any IDE, you need to checkout the langtools hg repository.
- Create a new eclipse project
- Add the langtools/src/share/classes folder from your openjdk install as a source folder.
- 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.
There is an existing netbeans project in the "langtools/make/netbeans/langtools/" directory of openjdk that can be opened.
- cd langtools/make
- ant -Dboot.java.home=$ALT_BOOTDIR
NB: replace $ALT_BOOTDIR with an existing JDK 7 installation.
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.