PriorityDoc

software/PriorityDoc.jpg{teaser}

Platforms : Linux, Windows
Language : Java
Source Code (GitHub)
Javadoc

About

A new design for javadocs. This isn't about aesthetics, this is about functionality and ease of use. Traditional javadocs don't do enough to help programmers understand an unfamiliar set of APIs. They do nothing to highlight the important packages, classes and methods. Traditional javadocs are visually poor, which hinders comprehension.

PriorityDoc features :

  • Shows only the most important methods. Those that are hidden can be revealed with a single key stroke, or mouse click.
  • Jump to methods based on their initial letter with a single key press.
  • Remove clutter by hiding fully qualified names; hover over a type to see its full package name.
  • Expand and contract method and field details.
  • Static fields and methods are separate from their non-static cousins.
  • Designed to be easy to scan through, by careful use of fonts, colours and icons and paring the text down to a minimum.

Usage

To use PriorityDoc on your own project, here's a typical build.gradle snippet :

dependencies {
    compile 'uk.co.nickthecoder:prioritydoc:0.1'
}

javadoc {
    source = sourceSets.main.allJava
    classpath = configurations.compile
    
    options.doclet = "uk.co.nickthecoder.prioritydoc.PriorityDoc"
    options.addStringOption( "mainpackage", "YOUR_MAIN_PACKAGE" )
    options.addStringOption( "title", "YOUR PROJECT'S TITLE" )
    options.addStringOption( "overwriteresources", "true" )
    options.addStringOption( "usecookies", "true" )
    options.addStringOption( "link", "http://docs.oracle.com/javase/7/docs/api/")
    
    options.docletpath = configurations.compile.files.asType(List)
    verbose = false
}

Priority Levels

There are 5 levels of priority, 1 being the most important, and 5 being the least important.

By default, the priorites are assigned as follows :

  • 5 Private methods/fields
  • 4 Package-private methods/fields
  • 3 Protected methods/fields
  • 2 Public methods/fields implemented in a superclass.
  • 1 Everything else

Notice that all fields and methods defined in a super class will not be shown while browsing at priority 1. This is in keeping with traditional javadocs, where the super class's methods are not described on the sub class's page. I personally don't like this, so I tend not to browse at priority 1.

Being able to see the description of methods implemented in a super class is a large difference between PriorityDoc and traditional javadocs. By its nature, it leads to large amounts of duplication, but IMHO, greatly increasing the usability of the documentation.

You can override these default priorities by adding a "priority" tag to your javadoc comments. e.g. :

/**
 * @priority 2
 */
public String hello = "Hello World";

When choosing priority levels, assume that a first time user of your class will browse at priority 1 or 2. As they become more experienced, they may want to create a sub-class. They will then browse at priority 3, to see the protected methods. Only the developer of the class should need to browse at priority 5.

The average user of your class, should be browsing at priority 1 or 2, so if you write public methods, which are very rarely used, then set their priority to 3.

Priority 1 Super Class Methods

Sometimes methods defined in a super class are important enough that they should have a priority 1. However, they aren't defined in your class, so how do we change their priority from the default of 2?

At present, you can't do it - that code hasn't been written yet! But here's how it will work...

There are two ways. If you own the superclass, you can add a javadoc tag of "@alwayspriority 1". This will cause the method to have priority 1 within all of its sub classes.

If you don't own the superclass, then you will have resort to adding tags to your class's javadoc section. :

/**
 * @methodpriority 1 setText, getText, setValue, getValue
 * @fieldpriority 1 text, value
 */
public Foo extends Bar
{
}

Note, there is no way to differentiate between overloaded methods. All methods with the same name will be given that priority.

You can include as many methodpriority and fieldpriority tags as you need.