RFR: JDK-8252717: Integrate/merge legacy standard doclet diagnostics and doclint

[Pavel Rappo]

On Thu, 2 Jun 2022 20:59:26 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a moderate change to enable (most) doclet warnings even if doclint is enabled.
> 
> Since the introduction of doclint, there was some (small) overlap between the small set of warnings generated by the doclet and the new larger set of diagnostics that could be generated by doclint.  The solution, until now, has been to disable doclet warnings when doclint is enabled. But, the sets do not overlap, and the policy has inappropriately suppressed some warnings and inhibited the generation of new warnings by the doclet that could only be done by the doclet, and not doclint.
> 
> One notable group of warnings that has been inappropriately suppressed is the warnings generated by using the `-serial warn` option.
> 
> The fundamental core of the change is to remove the conditional checks in the doclet `Messages.java`, which would suppress messages when doclint was enabled.  A consequence is that some specific messages have to disabled if they are duplicate checks if doclint is enabled. (The messages cannot be removed altogether because doclint might _not_ be enabled.)   A test is added to verify that either one message or the other is generated, but never both.
> 
> As previously noted, an issue with the earlier policy is that warnings generated by using the `-serial warn` option were inappropriately suppressed, and this change fixes that ... revealing a number of latent warnings in the JDK API that need to be addressed.  The short term fix here is to temporarily remove the use of the `-serialwarn` option. See [JDK-8287749](https://bugs.openjdk.java.net/browse/JDK-8287749).

> Since the introduction of doclint, there was some (small) overlap between the small set ... and the new larger set ... But, the sets do not overlap

Do or do they not overlap? :)

> the policy has inappropriately suppressed some warnings and inhibited the generation of new warnings

What's the difference between "suppressed" and "inhibited" here?

Generally, how can we be sure that we haven't missed any double-reported cases?

test/langtools/jdk/javadoc/doclet/testDoclintDocletMessages/TestDocLintDocletMessages.java line 136:

> 134:         var doclintResult = new Result(Exit.OK, "C.java:8: warning: @param \"x\" has already been specified");
> 135:         var docletResult  = new Result(Exit.OK, "C.java:8: warning: Parameter \"x\" is documented more than once.");
> 136: 

Both are warnings, hence two `Exit.OK` results; I see.

test/langtools/jdk/javadoc/doclet/testDoclintDocletMessages/TestDocLintDocletMessages.java line 190:

> 188:         checkExit(expect.exit);
> 189: 
> 190:         checkOutput(Output.OUT, true,expect.message);

Add whitespace after `true,`

-------------

PR: https://git.openjdk.java.net/jdk/pull/9006