How to intelligently fix documentation in Eclipse?

Question

Back in my C# days, I loved using a Visual Studio extension called "GhostDoc". Now that I'm a being used as a Java developer I'm using Eclipse. I can live without being able to have inferred documentation, but something that I'd like to do is to intelligently "fix" my documentation. For example, let's assume I have the following method:

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(int bar, int baz)
{
    // Do something cool
}

Later on in development I realize that it would be useful to allow the consumers of my method to pass in a qux value. Not only that, but it makes the most sense to have it as the first parameter. Also I'm going to have the method throw my super useful FooBarException. So now my method looks like this:

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(String qux, int bar, int baz) throws FooBarException
{
    // Do something cool
}

Being a good developer, I want my changes reflected in my JavaDoc. In GhostDoc I could hit my document shortcut key and it would add in the new stuff without disturbing the old stuff. In Eclipse, it renders a whole new set of JavaDoc and I have to do a bunch of copy pasta-ing. How can I automatically put in the new @param, @exception, and the missing @returns parameter into my JavaDoc without losing the JavaDoc that I currently have?

Answer 1

Not sure if the following is what you ment, but since eclipse has its own JavaDoc Validator, you can configure compile Warnings/Errors under

Window -> Preferences -> Java -> Compiler -> JavaDoc.

With activating missing javadoc tags on your own needs and setting warning level to "warning", the compiler will notice your changes and give you a warning, as soon as your javadoc differs from your methods signature. To fix it, it offers a quickfix (STRG+1) and you can choose add all missing tags. This operation will add the missing tags even in the right place without messing with your old comment.

Answer 2

Eclipse support "code"-completion for JavaDoc too. You do not have to type the hole statement. You only have to type "@p" and CTRL+Space will print the rest for you. Or even better, just write the name of the parmeter, code-completion will add the rest.

It is not directly a shortcut, but you can faster ehhance the javadoc than to write everything from scratch.

same for @t (@throw) @r (@return) and so on.

Edit to your comment:

You can configure Checkstyle, for checking your classes automatically. Checkstyle will report when your method has a non documented parameter or some other missing parameters. Checkstyle can also check, whether your first sentence ends with a '.' or not. You can a lot of such rules by hand.

Checkstyle will add problem markers in your java code editor and your problems view. So you can find easily code lines, with javadoc problems.

Answer 3

Typing /** above a typical comment place (same places as with GhostDoc) will auto complete a template for the comment.

If you change the name of a variable using the rename functionality (Shift+Alt+R) then Eclipse will change the names in all the right places too, assuming the code compiles.

This includes and comment links you've made

/**
 *
 * My funky method
 *
 * @param myThing
 *         myThing is of type {@link MyThingClass}
 */
 public void myMethod(MyThingClass myThing) {}

Renaming either myThing or MyThingClass using Eclipse's renaming functionality will update these references too.

Likewise, using the "Change Method Signature' functionality will update your comments too.

Basically, if you're refactoring at all, use the refactoring menu (Shift+Alt+T).

Answer 4

http://jautodoc.sourceforge.net/ works well with Luna as well please check in the market place

Answer 5

Checkstyle was already mentioned. I tried it, but it seemed to slow down my Eclipse a lot (E4 juno though, that is known for having some bad slowdowns).

Google CodePro was doing a better job, so I'm now using this now.

And of course you can enable JavaDoc warnings.