RFR: 8320234: Merge doclint.Env.AccessKind with tool.AccessKind

[Jonathan Gibbons]

On Fri, 17 Nov 2023 18:14:53 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Back when DocLint lived in jdk.compiler, neither jdk.javadoc had access to DocLint, nor DocLint had access to jdk.javadoc. Since DocLint moved to jdk.javadoc, some redundancy can be eliminated and functionality shared; AccessKind is one such functionality.
> 
> There's more that could be done here. For example, jdk.javadoc.internal.doclint.Messages.Options can be simplified more. However, it's a separate issue.

OK, but with discussion.

In a different reality, Java platform for modules would be smaller, and in particular, the `jdk.javadoc` module would be factored into at least two: one for the tool, one for the standard doclet, where the standard doclet only interacts with its environment through public API, such as the Language Model API, Compiler Tree API, and the (public) Doclet API.  It's not clear where `doclint` would be in that reality, but most likely either in its own module or in the same module as the standard doclet.

Even though we're not in that reality, we have tried to keep a hands-off relationship between the javadoc tool and the standard doclet, to avoid spaghetti-code relationships between the parts of the `jdk.javadoc` module.

Thus, it is somewhat jarring to see internal tool API leaking into other parts of the module, even if it is "only doclint".

That being said, I expect that the long-term future for doclint is to be merged into the standard doclet (and support phased out for doclint in javac). If that comes to pass, the outer layers of the doclint onion dealing with invocation will go away, just leaving some evolved form of the `Checker` class.  In other words, down the road, doclint will likely not need the `Env` class or `AccessKind`/`AccessLevel` at all, since the environment and comments to be checked will be mediated by the tool and standard doclet.

All of which is a long-winded way of saying that this merge is effectively a temporary state of affairs, until we see how doclint is going to evolve even further.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/AccessLevel.java line 59:

> 57:                 && PROTECTED.ordinal() == 2
> 58:                 && PUBLIC.ordinal() == 3;
> 59:     }

While not wrong, this is a weird not-recommended use of `.ordinal()`.
How much is the order actually relied on?

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

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/16714#pullrequestreview-1737979618
PR Review Comment: https://git.openjdk.org/jdk/pull/16714#discussion_r1397916007