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?

Schwarz

The Eclipse Java editor would have to be modified to do this, so I would say no. – Deel

You could always create your own plugin for Eclipse that would check all methods in a class and if the javadoc corresponds to the parameters, exceptions.. then have it insert default values for those tags. See this tutorial by Vogel... maybe I'll do it next time I have nothing to do, because I tend to refactor my code after I write the javadoc. – Torrential

The Eclipse JDT would also help in this process. – Torrential

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.

Weep

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.

Emmettemmey

That's nice. But what it doesn't do is detect when I have parameters with missing documentation, missing return documentation, missing method descriptions, missing exception documentation, etc... I do my best, but I'm only human. So a tool like GhostDoc is remarkably useful. – Schwarz

Thats not correct! We use this mechanism in our company and i do get problem markers in all of these cases. – Emmettemmey

Hi Markus. My comment was in response to your original answer. In response to my comment, you amended your answer. This amended answer is accurate and what I was looking for. Thanks. – Schwarz

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).

Lie

I try to do this, but sometimes things happen such as another developer committing changes to version control that did not refactor this way. While preventing this scenario is ideal, I'm really looking for a way to fix it when it does happen. – Schwarz

@JasonThompson Ahh. I don't know of a way to do that, maybe recomment PMD & CheckStyle to enforce these things on check-in? Likewise, give the devs responsible a hard time for checking in half-arsed code. It works here. – Lie

Answer 4

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.

Diacritic

Answer 5

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

Duly