The Cool Auto Comment Tool In NetBeans 4.0 - Now Documentation can be fun!

Introduction

Sorry I had to make you laugh with the title otherwise you would not read an article on writing documentation.
I have always liked the JavaDoc tool in the JDK Sun have released, it’s a good way to point future developers/Maintainers of your code in the right direction. Or if you’re like me, to point yourself in the right direction when you have forgotten how your code works after a few months/weeks/days.

What Can The Auto Comment Tool Do For Me?

Well it will not write your documentation for you. You still have to do that, however it will format/structure your comments in a JavaDoc friendly way.
Plus and this is key, it will flag up missing comments. This is a more natural way to validate your Java comments. Before I started using NetBeans or discovered the Auto Comment tool, I would run the JavaDoc tool and change my comments or parameters based on the warnings I received. This method is time consuming / boring and means there was a higher chance I would get it wrong. Using the Auto Comment tool you are alerted immediately to errors or omissions and can correct the error then and there not always having to flip back to code to correct.

How Do I Use The Auto Comment Tool?

1. Open a Netbeans project
2. Open a Java file or select the Java file or class node in the Projects window. If you do not, the Auto Comment tool is not available. The Auto comment tools use is all based on context. If you run auto comment tool on another class it will not open another instance of auto comment. This means you can only edit the comments for one Java file at a time. You can not run Auto Comment on a project as a whole (Hint for a feature)
3. From the menu tools select Auto Comment…

Once the Auto Comment tool is open, in the left pane you will see your list of methods in your class and a series of buttons with icons in them.

These buttons are filters. If you have a class with a high number of methods and variables the Auto Comment filters help you to focus on just what needs to be commented.

Using Auto Comment Filters

Click on the first button to the left. This button will look like a green box with a white tick in it. It is a toggle button. When this button is depressed all the comments that meet the JavaDoc specification are displayed.

If you want a more detailed explanation of the filter buttons. Go to the Help menu and click on Help contents. Then click on the search tab and enter the keywords Auto Comment. Or simply click on the help button next to the list of methods in the Auto Comment tool.

Note the icons displayed next to each method in the list of your class below the filter buttons.

Java Comment Is OK Icon

The icon that looks like a green box with a white tick in it is displayed means the comments for that method or variable meet the JavaDoc specification and there is no additional work for you to do. Apart from check you have entered a relevant/accurate/up to date comment about the method or variable.

Missing Comments Icon

If you see an icon that looks like a red box with a white X in it, this means the methods comments do not meet the JavaDoc specification or don't have any comments associated with it. When I first started using JavaDoc sometimes I would write my comment blocks like this...

/*
* Java rocks
*/

Of course nothing appeared in the Java docs because I missed an extra star. If you enter the comments via Auto Comment in the JavaDoc Comment text: text field auto comment writes your comments to your code with the correct formatting for example.

/**
* Java rocks

*/

If the error is missing comment. Auto Comment warns you in the list box below the list of methods. The error message below that will be JavaDoc comment is missing . If you have already commented the method or variable and its flagging up this error you can check you have not missed that extra * by clicking on the view source button. Again like everything in the Auto Comment tool its all based on context. If you don't have a method selected the view source button will be greyed out.

Partial Error Or You Got It Totally Wrong Icon

The icon we are most interested in is the partial error icon this looks like a triangle with a thunder bolt through it. Most of the time you will see this error when you don't include a @param tag in your methods comments that have parameters. Auto Comment will tell you which parameter has the missing tag for example. The tag for the parameter <Your parameter name> is missing.

Another example of when you will receive the partial error is when you add unnecessary tags to a comment. For example if you add the author tag to a class method not the class. Look at the example below.

/**
 * This method does something
 * @param Something
 * @Author Jason Stapley – This is an error. Not me, the Author tag!
 */
Void doSomething(String Something) {
    System.out.println(Something);
}

You can correct this type of error in Auto Comment by selecting the unwanted tag in the tag list and clicking on the delete button. Which leads nicely into the next heading adding tags.

Adding Tags To Your Comment Blocks

Click on the new... button under the tags list in the Auto Comment tool and you will see the new tag window. This lists the types of tags you can add to your comment block. The most common tags are @Param and @Return after you select what type of tag you want, if its a parameter you must name it in the parameter field. The parameter must match the parameter in your method. Don't worry if you get it wrong Auto Comment will flag it up.

Next add your comment in the Description field. Repeat until all your parameters and return statement is commented. Click on another method or click on refresh. The method you just commented should change to the Comment ok icon. If not check the error message text box below the list of methods for the reason why there is a problem.

Tag Order

You don't have to put your tags in any defined order for you JavaDoc to be correct. Its whatever is logical to yourself, and to others who read your code. Using Auto Comment, you can change the order of the tags in your comment block. For example if you want the return tags to always be the last tag in the list you would select it and move it to the bottom of the list by clicking on Move Down button. If you want it at the top of the list you would select it and click on the Move Up button again these buttons are only available in the context of what you are doing.

HTML Tags

Because JavaDoc creates HTML you can add HTML tags to your comments. Select a method or a field you want to comment and in the JavaDoc Comment Text: field type < and wait a few seconds you should see a list of tags you can use Just like when you are editing code you can type an object name and then the dot and you see a list of methods this does the same for tags. You have the auto complete feature in tags Description field as well.

There are also a selection of the most commonly used tags in JavaDoc at the Bottom right of the Auto Comment screen these being <B> <I> <U> <CODE> <PRE> <@link>.

Very powerful.

Refreshing Auto Comment

Sometimes you have to go back to your code. For example when you forget to start your comment block with two stars Auto Comment can't find your comment so you have to click on View source and check. If you have made a mistake and then you flick back to Auto Comment its always a good idea just to click on the refresh button just to make sure you don't duplicate your work.

Auto Correct

Lets say you have a method that has many parameters typing all the parameter names would take sometime. The Auto Correct feature creates all the parameter tags and names them for you so all you have to do is add the comment. You do this by selecting the method you want to comment and clicking on the Auto Correct button you then add your comments in the parameter Description field.

When Your Finished

Make sure you save your hard work by clicking on the save all button in your tool bar.

Conclusion

Now you know how to use the Auto Comment feature and how much time it can save you. There will be no excuse not to comment your code. As an experiment, run it on some of your old code you will be in for a surprise!!