Javadoc Analyzer in NetBeans 6.1

NetBeans 5.5 contained a useful tool called the ‘Javadoc Auto Comment’ feature. With the heavy rewrite of the NetBeans internals in version 6.0, the auto comment tool as we knew it was stripped out. This was down with some howling and protests, but at least there was a good reason (and not simply for the heck of it).

Quoted from NetBeans Wiki:

‘We have intended to replace the AC tool for a long time due to its archaic UI and a weak linkage to the editor, where users usually want to edit source code. Changes in the Java model in NetBeans 6.0 forced us to drop the tool immediately and start to implement particular features that will replace the tool as resources permit. So NetBeans 6.0 contains basic editor hints to create or fix javadoc, and the long-awaited ability to generate javadoc skeleton on /** + <Enter> in the open editor as the first step. Of course, the Javadoc Search and the Show Javadoc were adapted to the new model as well.’

NetBeans 6 did contain Javadoc hints and warning so on a class by class basis you could see what was missing or incomplete. NetBeans 6.1 introduced Javadoc code completion. So far so good, but it wasn’t quite as useful as the old Auto Comment tool.

I recently checked the NetBeans 6.1 update center and discovered a plugin listed called Javadoc Analyzer. I had been following several related bug posts at the NetBeans site and knew they had been working on it, but had not had time to try it out.

Download it from the update center and you’re ready to use it with no configuration.

Let’s start with this class.

package com.pronetbeans.samples.utils;

public class StringUtils {

public String stupid = “”;

protected String sortOfStupid = “”;

private int someVar = 100010;

private final int someVar2 = 100010;

private static final int someVar3 = 100010;

public String completelyMissing(String arg) {
System.out.println(someVar);
return arg.toUpperCase().trim();
}

/**
*
* @param x
* @return
*/
public String partiallyMissing(int x, int y, int z) {

return x + “, ” + y + “, ” + z;
}
}

In the code above, I have several class member variables with different access modifiers to test and demonstrate if they are handled differently. I also have two methods: completelyMissing – which contains absolutely no Javadoc; and partiallyMissing – which has some Javadoc filled out, but is missing 2 @param tags.

With the Javadoc Analyzer tool installed, you can select a Java project node in the Projects window, the Source Packages node so that all packages and classes are scanned, a specific package node underneath Source Packages, or a specific class in a package. Then select Source >> Analyze Javadoc. The Analyzer will run and display results in the Analyzer Window, typically along the bottom section of the IDE window by default, as shown in Figure 1. If the window is not displayed or you close it accidentally, you can re-open it manually by selecting Window >> Analyzer.

NetBeans Javadoc Analyzer displaying results
Figure 1. The Javadoc Analyzer window displayiong results

Each piece of missing Javadoc will be displayed as an item in the Analyzer Window. If you have used the NetBeans Refactoring Preview feature, this style of displaying results should look quite familiar.

The Analyzer suggests missing Javadoc for the class definition, the stupid class member (which is public), the sortOfStupid class member (which is protected), the completelyMissing method (since there is no Javadoc for it), and the 2 missing @param tags for the partiallyMissing method. Notice that it did not suggest to create Javadoc for the three private class members variables, someVar, someVar2, and someVar3. Typically you don’t create Javadoc for private variables and methods.

NetBeans Java projects typically have a parameter for this in the project’s properties section. You can right-click the project name in the Projects Window and select Properties. In the Project Properties window that appears, the Documenting node contains a checkbox field labeled ‘Include Private and Package Private Members’. I selected the checkbox and re-executed the Javadoc Analyzer. To some disappointment, the Analyzer does not seem linked to this project-specific property as the private members did not get included in the Analyzer Window. It’s a small point, but might make a nice addition to the tool to keep it synced tightly with NetBeans.

Once you see the list of Javadoc that should be created, you can select the checkbox next to each item, the top-level package, or the entire project and click the Fix Selected button. This will cause the Javadoc for the selected items to be generated in the class, across the package, or the entire project depending on what you selected.

The Analyzer Window contains a Refresh icon and two arrows on the left side. You can use the arrows to navigate the list of suggested Javadoc fixes one at a time. As you click the down arrow and an item is selected, the Java file where the issue is contained opens and is displayed in the Source Editor. This seems like a nice way to traverse the issues and see the specific code. As you fix issues in the list, the item is crossed out visually, which I thought was a better approach to simply having it disappear. This way you have a better visual method for identifying what has and has not been done.

My last test I did with the Javadoc Analyzer was a large project test. I modified the class above to have approximately 20 methods, each with 4 parameters and absolutely no Javadoc. I then copied and refactoring this class into 20 copies of the class so I essentially had 400 methods with no Javadoc. I know this doesn’t really qualify as a large project, but it’s a basic test. With the Analyze Javadoc window still open, I clicked the Refresh icon in the upper left. A small popup window with a progress bar appeared briefly while the Analyzer ran.

I didn’t time it, but would say it ran and displayed results in less than 2 or 3 seconds. The only slightly disappointing part was when I clicked the Fix Selected button after selecting the checkbox next to the entire project. The Analyzer attempted to fix 20 classes with 20 methods each (and several member variables each), as shown in Figure 2. I actually counted slowly in my head, and got up to 17 seconds before the items in the Analyzer Window got crossed off and the process finished.

Javadoc Analyzer in NetBeans 6.1 with results
Figure 2. Analyzer finished with results.

In conclusion, I would say that the Javadoc Analyzer is a cool little tool. It essentially accomplishes what the auto comment tool did. You can identify missing Javadoc across the entire project and automatically fix it. So far it looks promising, but I’ll be thinking about ways to suggest improving it.

Anybody care to comment on any specific features of the Javadoc Analyzer I missed or left out?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>