Suppressing Javadoc 21 DocLint warnings specifically for "no main description"

Question

I just upgraded my build from Java 17 to Java 21. In Maven I have Javadoc set to DocLint everything using the Maven Javadoc Plugin -Xlint:all compiler option.

As is typical with Java classes, I have a plethora of getters in the following form:

  /** @return foo. */
  public Foo getFoo() {
    return foo;
  }

In Java 17 that produced Javadocs just fine. Now in Java 21 I get the following warning (oodles of them!) throughout my large codebase:

warning: no main description

It seems Javadoc now wants me to do this:

  /**
   * Returns foo.
   * @return foo.
   */
  public Foo getFoo() {
    return foo;
  }

I struggle to understand the utility of this new warning. I would like to suppress this warning project-wide in the configuration.

I believe I can disable the entire DocLint group by using -Xdoclint all,-missing, but this will suppress all warnings related to missing Javadocs. I definitely want to be warned if I leave off the Javadoc altogether for a getter!

How can I suppress only the Javadoc DocLint warning related to a missing "main description" if the @return is nevertheless present? Alternatively, if this is not possible, how best can I communicate to the Javadoc team that adding more and more inane warnings that cannot be suppressed individually will at some point cause even those users (such as I) who like to keep our API documentation super tidy to abandon the user of the linter altogether?

While I understand that someone people will just turn off the linter entirely, I'd rather be more specific.

See also my separate (related) question Turn off Java 17 doclint missing comment warning only for enums in Maven Javadoc Plugin.

Answer 1

Seems unlikely to have such granularity.

As you perfectly stated the message and check was included in 21 https://github.com/openjdk/jdk/blob/jdk-21%2B35/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties#L43

And having reviewed the change that implemented the new check there's no clue that such granularity for disabling the check can be achieved (needed to clone due to github being incapable of showing such a large diff).

@localhost:~/dev$ git clone [email protected]:openjdk/jdk.git
@localhost:~/dev/jdk$ git diff jdk-17+35 jdk-21+35 -- src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java > ~/jdk.diff

You'd probably be able to contact the team and/or submit your proposal/PR or feedback on this kind of changes, there's a community list [email protected] as described in https://mail.openjdk.org/mailman/listinfo/discuss but it's highly unlikely you see a change on this regard anytime soon.