Javadoc warn on no comment

Question

Is there a way (preferably via an argument, taglet, doclet or similar) to get Javadoc to generate a warning if there is no javadoc comment provided for a method or class? I've had a scout around at the options and Googled but can't see anything that stands out as being relevant. I'm currently working on a project where everything needs to have some form of Javadoc comment and this would be really useful for that purpose.

EDIT: I know such things can be enforced via code quality tools such as checkstyle, I was just wondering if there was a way to configure Javadoc to warn about different things such as this.

Ironically found this question while looking for a way to tell javadoc _not_ to warn on missing comments. ;) — Hakanai, May 30 '23 at 05:45

score 8 · Answer 1 · answered Mar 09 '11 at 10:00

8

You might try checkstyle to enforce such conventions.

answered Mar 09 '11 at 10:00

Thomas

87,414
12
119
157

Thanks for making me discover this :) – Dunaril Mar 09 '11 at 10:04
Yes, checkstyle is the best bet and any violations with severity of error type will fail the build. – asgs Mar 09 '11 at 10:05
Thanks, this is well worth pointing out and I may well fall back to using checkstyle to do this. I just wondered if there was a simple Javadoc option I was missing that anyone knew about. – Michael Berry Mar 09 '11 at 10:05

score 2 · Accepted Answer · answered Mar 09 '11 at 14:48

If you really wanted to use Javadoc, a custom checking doclet would be the way to go.

Here is an example:

package de.fencing_game.paul.examples.doclet;

import com.sun.javadoc.*;

public class CheckingDoclet extends Doclet {

    private static void checkElement(ProgramElementDoc ped,
                                     DocErrorReporter err) {
        if(ped.commentText().equals("")) {
            err.printError(ped.position(), ped + " has no documentation!");
        }
    }

    private static void checkAll(ProgramElementDoc[] array,
                                 DocErrorReporter err) {
        for(ProgramElementDoc ped : array) {
           checkElement(ped, err);
        }
    }

    public static boolean start(RootDoc root) {
        for(ClassDoc clazz : root.classes()) {
           checkElement(clazz, root);
           checkAll(clazz.constructors(), root);
           checkAll(clazz.fields(), root);
           checkAll(clazz.enumConstants(), root);
           checkAll(clazz.methods(), root);
        }
        return true;
    }
}

Running the doclet on itself (with ant) gives this output:

doccheck.doclet:
  [javadoc] Generating Javadoc
  [javadoc] Javadoc execution
  [javadoc] Loading source files for package de.fencing_game.paul.examples.doclet...
  [javadoc] Constructing Javadoc information...
  [javadoc] de/fencing_game/paul/examples/doclet/CheckingDoclet.java:7: error - de.fencing_game.paul.examples.doclet.CheckingDoclet has no documentation!
  [javadoc] de/fencing_game/paul/examples/doclet/CheckingDoclet.java:7: error - de.fencing_game.paul.examples.doclet.CheckingDoclet() has no documentation!
  [javadoc] de/fencing_game/paul/examples/doclet/CheckingDoclet.java:9: error - de.fencing_game.paul.examples.doclet.CheckingDoclet.checkElement(com.sun.javadoc.ProgramElementDoc, com.sun.javadoc.DocErrorReporter) has no documentation!
  [javadoc] de/fencing_game/paul/examples/doclet/CheckingDoclet.java:16: error - de.fencing_game.paul.examples.doclet.CheckingDoclet.checkAll(com.sun.javadoc.ProgramElementDoc[], com.sun.javadoc.DocErrorReporter) has no documentation!
  [javadoc] de/fencing_game/paul/examples/doclet/CheckingDoclet.java:23: error - de.fencing_game.paul.examples.doclet.CheckingDoclet.start(com.sun.javadoc.RootDoc) has no documentation!
  [javadoc] 5 errors

BUILD SUCCESSFUL
Total time: 2 seconds

If we want this to be not successful whenever one error is found, we should return false from the start-method in this case.

Is there a newer version without `com.sun` package for java 8? I saw only from Java 9 https://docs.oracle.com/javase/10/docs/api/jdk/javadoc/doclet/Doclet.html — Ori Marko, Oct 09 '18 at 09:32
I didn't work with Javadoc recently, so I didn't try this. The [package summary page](https://docs.oracle.com/javase/10/docs/api/index.html?jdk/javadoc/doclet/package-summary.html) has some kind of migration guide, but I'm not sure how easy it is to apply that in this case. — Paŭlo Ebermann, Oct 10 '18 at 15:24

score 1 · Answer 3 · answered Mar 09 '11 at 10:01

This task is best done with a code analysis tool like PMD or FindBug (possibly check style) as these are designed find these sort of issues and much more.

IntelliJ has a builtin checker which can help populate missing javadoc content as well as sanity check/spell check it.

Javadoc warn on no comment

3 Answers3

Linked