RFR: 8314213: DocLint should warn about unknown standard tags

[Pavel Rappo]

On Wed, 16 Aug 2023 16:51:50 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This PR is primarily informational: aside from adding a few code comments and `assert` statements, it acts as a place to record observations on unknown JavaDoc tag reporting mechanics. Because it's a PR, this text will be automatically sent to the javadoc-dev mailing list and archived for future reference.
> 
> ---
> 
> DocLint can be run in three modes:
> 
>   * from javac (i.e. `javac -Xdoclint`)
>   * from javadoc (i.e. `javadoc -Xdoclint`)
>   * as a standalone test tool (i.e. `test/langtools/tools/doclint/DocLintTester.java`)
> 
> While the core of all these modes is the same, `jdk.javadoc.internal.doclint.DocLint`, and is capable of reporting on unknown tags, whether an unknown tag will be reported, depends on the core configuration, which differs significantly among these modes.
> 
> The latter mode is for testing only and can be configured flexibly, but it's of little interest to us. The former two modes are important as they face end user, but are limited in their configuration and, additionally, each has own peculiarities.
> 
> In javac mode, DocLint cannot be passed with a list of custom tags: the required wiring is missing. So, when a potentially unknown tag is detected, the error is not raised because `env.customTags == null`:
> 
>     private void checkUnknownTag(DocTree tree, String tagName) {
>         if (env.customTags != null && !env.customTags.contains(tagName))
>             ^^^^^^^^^^^^^^^^^^^^^^
>             env.messages.error(SYNTAX, tree, "dc.tag.unknown", tagName);
>     }
> 
> This is why we don't see errors for JDK-specific tags (e.g. `@implSpec`, `@implNote`, `@apiNote`, `@jls`) when `make images`, during which DocLint is run from javac.
> 
> In javadoc mode DocLint is passed with a list of custom tags, containing tags captured from `-tag` and `-taglet` options. Because `make docs` runs javadoc with such options for each of the JDK-specific tags, all tags are known, and no errors are reported.
> 
> Here's a twist though: javadoc has its own machinery for reporting unknown tags. So why don't we see doubling of diagnostics? There should be an error from DocLint and a warning [sic!] from javadoc, but there's only an error. Here's why:
> 
>     public void checkTags(Element element, Iterable<? extends DocTree> trees) {
>         CommentHelper ch = utils.getCommentHelper(element);
>         for (DocTree tag : trees) {
>             String name = tag.getKind().tagName;
>                               ^^^^^^^^^^^^^^^^^
>             if (name == null) {
>                 continue;
>             }
>       ...

I forgot to add one important point. tier1 now also does `make docs`: if there are doc errors, including unknown tags, they will be caught early. Whether doc build succeeds or fails, can be seen, for example, in PR checks (Pre-submit tests - docs / build - Build / test).

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

PR Comment: https://git.openjdk.org/jdk/pull/15314#issuecomment-1680966004