RFR: 8314213: DocLint should warn about unknown standard tags

[Pavel Rappo]

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;
            }
            if (!name.isEmpty() && name.charAt(0) == '@') {
                name = name.substring(1);
            }
            if (! (standardTags.contains(name) || allTaglets.containsKey(name))) {
                if (standardTagsLowercase.contains(Utils.toLowerCase(name))) {
                    messages.warning(ch.getDocTreePath(tag), "doclet.UnknownTagLowercase", ch.getTagName(tag));
                    continue;
                } else {
                    messages.warning(ch.getDocTreePath(tag), "doclet.UnknownTag", ch.getTagName(tag));
                    continue;
                }
            }

Unknown tags are modelled by two `DocTree` subinterfaces, `UnknownInlineTagTree` and `UnknownBlockTagTree`, each of which return the name of the captured tag from `getTagName()`, not from `getKind().tagName`, which (unsurprisingly) returns null for those two kinds. That means that the body of this `if` block is dead code (i.e. DocLint or not, it's never reached for an unknown tag):

            if (! (standardTags.contains(name) || allTaglets.containsKey(name))) {

Here's another twist: DocLint can be disabled for a javadoc run: `-Xdoclint:none`. When coupled with defunct javadoc reporting, disabled DocLint means that no unknown tags are reported.

I don't know which of the above is by mistake and which by design, but it's how it works today. We could address (some of) that in a later PR. Personally, I wouldn't provide missing wiring in javac, given that javac mode has been recently somewhat de-emphasized. That said, I think we should repair javadoc reporting and make sure that either DocLint or javadoc, but not both, report on unknown tags at all times (i.e. whatever the javadoc configuration might be).

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

Commit messages:
 - Initial commit

Changes: https://git.openjdk.org/jdk/pull/15314/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=15314&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8314213
  Stats: 16 lines in 2 files changed: 15 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/15314.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/15314/head:pull/15314

PR: https://git.openjdk.org/jdk/pull/15314