Javadoc 警告没有评论

Question

如果没有为方法或类提供 javadoc 注释，是否有一种方法（最好通过参数、taglet、doclet 或类似方法）让 Javadoc 生成警告？我已经对这些选项进行了侦察，并在谷歌上进行了搜索，但看不到任何突出的相关内容。我目前正在开发一个项目，其中所有内容都需要某种形式的 Javadoc 注释，这对于该目的非常有用。

编辑：我知道这样的事情可以通过代码质量工具（例如 checkstyle）来强制执行，我只是想知道是否有一种方法可以配置 Javadoc 来警告诸如此类的不同事情。

Answer 1

您可以尝试 checkstyle 来强制执行此类约定。

Answer 2

如果您确实想使用 Javadoc，那么自定义检查 doclet 将是最佳选择。

下面是一个示例：

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;
    }
}

运行 doclet 本身（使用 ant）给出以下输出：

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

如果我们希望在发现错误时不成功，则在这种情况下我们应该从启动方法返回 false。

Answer 3

较新的 JDK 支持显式的 -Xdoclint:missing 标志。

例如，在 JDK 17 中：

$ javadoc -X
...
    -Xdoclint:(all|none|[-]<group>)
                  Enable or disable specific checks for problems in javadoc
                  comments, where <group> is one of accessibility, html,
                  missing, reference, or syntax.

请注意其中的 missing 选项。

Answer 4

此任务最好使用 PMD 或 FindBug（可能是检查样式）等代码分析工具来完成，因为这些工具旨在查找此类问题以及更多问题。

IntelliJ 有一个内置检查器，可以帮助填充缺失的 javadoc 内容以及对其进行健全性检查/拼写检查。