Are There Any Tools For Updating Javadoc Automatically?

Question

I work on a code base that is ... messy. One aspect of this messiness is that we have a ton of methods whose signatures no longer match the associated Javadoc. For instance:

/**
 *
 * @ param foo
 */
public void doFoo(int bar) {...

I'm no fan of generated Javadoc (as it's almost always worthless), but I really could use a tool that would go through our code, find cases like that, and:

1. remove the javadoc for the "foo" param
2. add javadoc for the "bar" param (but just a blank one, no auto-generated doc or anything)

Does such a tool exist? If not, does a tool that just does #1 exist? Even that much would significantly reduce the amount of garbage warnings we get in our builds. Thanks.

Answer 1

NetBeans has a tool for that. It does exactly what you ask.

You can either click on the Tools Menu, then Analyze Javadocs from the top, or right click on a file and click Tools, then Analyze Javadocs.

This then give you a list of all problems it finds with your Javadocs with an option to fix it. It allows you to fix a single problem in a method, fix the javadocs for the method, for the file, for the package, or for the entire project.

Answer 2

One solution, if you're using eclipse, is to go to Window -> Preferences -> Java -> Compiler -> Javadoc and then set the 'Malformed Javadoc comments' variable to warning or error.

You can then go to the problems view Window -> Show View -> Problems and then on each error right click and select 'Quick Fix'.

Answer 3

I have not tried any of these other than DocCheck, but this somewhat-dated page on Sun's site lists several third-party doclets, some of which purport to insert Javadoc into your source. Of those, you might take a look at Doc-o-Matic, JRefactory Pretty Printer, and ACTOS Auto Commentator for Java. Again, I have not tried any of these, but it's a place to start.