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).

Looks good.

> I did a visual inspection over the Checker class.

> The test is set up to be a framework to accommodate new cases if any should arise.

This is good. It would be even better if we had a mechanism to reduce risk of diagnostic duplication in the future. I don't have any concrete proposal, but unique internal error codes shared between doclint and doclet come to mind.

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

Marked as reviewed by prappo (Reviewer).

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