8320234: Merge doclint.Env.AccessKind with tool.AccessKind #16714
Conversation
"Level" matches relevant comments better than "Kind" does.
Embraces enum ordering. At least for now. Also adds comments and changes language to match that of JLS.
|
👋 Welcome back prappo! A progress list of the required criteria for merging this PR into |
|
@pavelrappo The following label will be automatically applied to this pull request:
When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command. |
Webrevs
|
jonathan-gibbons
left a comment
jonathan-gibbons
left a comment
There was a problem hiding this comment.
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.
| static { // self-test to catch unintended reordering of the constants | ||
| assert PRIVATE.ordinal() == 0 | ||
| && PACKAGE.ordinal() == 1 | ||
| && PROTECTED.ordinal() == 2 | ||
| && PUBLIC.ordinal() == 3; | ||
| } |
There was a problem hiding this comment.
While not wrong, this is a weird not-recommended use of .ordinal().
How much is the order actually relied on?
There was a problem hiding this comment.
A different solution, if one is really needed, would be a regression test to verify the expected order.
There was a problem hiding this comment.
Yet another alternate suggestion would be to use something like
assert List.of(AccessLevel.values())
.equals(List.of(PRIVATE, PACKAGE, PROTECTED, PUBLIC)
although I still think it is paranoid (and non-standard) to assert the order of enum members for any enum that is used as Comparable
There was a problem hiding this comment.
How much is the order actually relied on?
Clients of doclint.Env.AccessKind use compareTo(), which is effectively defined through ordinal().
A different solution, if one is really needed, would be a regression test to verify the expected order.
There are such tests already. For example, DocLintReferencesTest.
Yet another alternate suggestion would be to use something like
assert List.of(AccessLevel.values()) .equals(List.of(PRIVATE, PACKAGE, PROTECTED, PUBLIC)
This is certainly shorter. However, my IDE no longer flags that assert statement as "always true".
I still think it is paranoid (and non-standard) to assert the order of enum members for any enum that is used as
Comparable
For better or worse, every enum exposes its constants' declaration order. That order may unexpectedly become relied upon elsewhere, and the author of the enum cannot do anything about it. To me, this is still a gotcha moment.
When I found that doclint.Env.AccessKind.compareTo was used, my initial reaction (after Yuck!) was to introduce explicit construction AccessKind(int level) and boolean instance methods, such as lessLimiting(AccessLevel), equallyLimiting(AccessLevel) and moreLimiting(AccessLevel), that would compare int levels that the constants were constructed with.
But on second thought, it felt like working against the language, which gives us all these features for free. So I decided to embrace that part of enums design and aid the next person who will look at this code, by adding a test, a comment or an assertion.
There were already a few tests, so I decided not to add more. An assertion and a comment together are better than just an assertion, which is better than just a comment. Assertion is a checked comment: it jumps out at you, it fails fast, and works nicely with a sufficiently smart IDE.
There was a problem hiding this comment.
For better or worse, every enum exposes its constants' declaration order. That order may unexpectedly become relied upon elsewhere, and the author of the enum cannot do anything about it. T
Since any enum implements Comparable, it is not reasonable to say that the order may be relied on "unexpectedly". It is an intentionally defined feature of the language design. And the author can do something about it: the author can choose not to reorder constants when the order is significant.
A more interesting design, back in the day, might have been to make Comparable an opt-in super type, but that's 20-20 hindsight and not the case.
There was a problem hiding this comment.
While it is not necessary to indicate that an enum implements Comparable, it is permissible to state it explicitly, such as in enum Foo implements Comparable<Foo> { foo1, foo2 }. which is a somewhat more linguistic way of writing /** The order of the constants is important. */ enum Foo { foo1, foo2 }
There was a problem hiding this comment.
Since any
enumimplementsComparable, it is not reasonable to say that the order may be relied on "unexpectedly".
What I mean is that not every enum client uses compareTo() or values()[0] and values()[values().length - 1] to get the opposite extremes of a certain enum class. Not every client uses EnumSet.range. However, given enough time, they likely, eventually will.
There was a problem hiding this comment.
I believe I addressed your concerns in 2def7bf.
|
@pavelrappo This change now passes all automated pre-integration checks. ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details. After integration, the commit message for the final commit will be: You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed. At the time when this comment was updated there had been 18 new commits pushed to the
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details. ➡️ To integrate this PR with the above commit message to the |
|
/integrate |
|
Going to push as commit 3aefd1c.
Your commit was automatically rebased without conflicts. |
openjdk
bot
removed
ready
|
@pavelrappo Pushed as commit 3aefd1c. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
2 participants
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.
Progress
Issue
Reviewers
Reviewing
Using
gitCheckout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/16714/head:pull/16714$ git checkout pull/16714Update a local copy of the PR:
$ git checkout pull/16714$ git pull https://git.openjdk.org/jdk.git pull/16714/headUsing Skara CLI tools
Checkout this PR locally:
$ git pr checkout 16714View PR using the GUI difftool:
$ git pr show -t 16714Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/16714.diff
Webrev
Link to Webrev Comment