Saturday, March 24, 2012

Eclipse: Writing Better, Faster Java Documentation

JAutodoc:
I've started using JAutodoc, which is an Eclipse plugin for automatically adding Javadoc to your source code. It helps generate the initial Javadoc for methods which don't have them and can even complete existing Javadoc by adding missing parameters and return types. I have found this plugin very useful in writing documentation fast.

Let's say you have the following method which adds two ints:

public int add(int x, int y) {
    return x + y;
}
To invoke JAutodoc, all you have to do is hit Ctrl+Alt+J inside the method and the following Javadoc template will be automatically generated, which you can then complete.
/**
 * Adds the.
 *
 * @param x the x
 * @param y the y
 * @return the int
 */
public int add(int x, int y) {
    return x + y;
}
Later on, if you decide to change this method by adding another parameter to it, you can press Ctrl+Alt+J again and JAutoDoc will add the new parameter to the Javadoc but leave the rest of it unchanged.

Enabling Eclipse Javadoc warnings:
I've also found it useful to turn on Eclipse warnings for missing or malformed Javadoc comments. You can do this by going to Window > Preferences and then selecting Java > Compiler > Javadoc. Tick the box for processing Javadoc comments and select your desired severity levels. I've got mine set to Warnings for everything. You can get my Eclipse preferences from my git repository.

1 comment:

  1. This comment has been removed by a blog administrator.

    ReplyDelete

Note: Only a member of this blog may post a comment.