Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8320234: Merge doclint.Env.AccessKind with tool.AccessKind #16714

Closed
wants to merge 7 commits into from

Conversation

pavelrappo
Copy link
Member

@pavelrappo pavelrappo commented Nov 17, 2023

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

  • Change must be properly reviewed (1 review required, with at least 1 Reviewer)
  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue

Issue

  • JDK-8320234: Merge doclint.Env.AccessKind with tool.AccessKind (Bug - P4)

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/16714/head:pull/16714
$ git checkout pull/16714

Update a local copy of the PR:
$ git checkout pull/16714
$ git pull https://git.openjdk.org/jdk.git pull/16714/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 16714

View PR using the GUI difftool:
$ git pr show -t 16714

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/16714.diff

Webrev

Link to Webrev Comment

"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.
@bridgekeeper
Copy link

bridgekeeper bot commented Nov 17, 2023

👋 Welcome back prappo! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk openjdk bot added the rfr Pull request is ready for review label Nov 17, 2023
@openjdk
Copy link

openjdk bot commented Nov 17, 2023

@pavelrappo The following label will be automatically applied to this pull request:

  • javadoc

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.

@openjdk openjdk bot added the javadoc javadoc-dev@openjdk.org label Nov 17, 2023
@mlbridge
Copy link

mlbridge bot commented Nov 17, 2023

Webrevs

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines 54 to 59
static { // self-test to catch unintended reordering of the constants
assert PRIVATE.ordinal() == 0
&& PACKAGE.ordinal() == 1
&& PROTECTED.ordinal() == 2
&& PUBLIC.ordinal() == 3;
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A different solution, if one is really needed, would be a regression test to verify the expected order.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 }

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since any enum implements Comparable, 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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe I addressed your concerns in 2def7bf.

@openjdk
Copy link

openjdk bot commented Nov 17, 2023

@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:

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

Reviewed-by: jjg

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 master branch:

  • 0712b22: 8320147: Remove DumpSharedSpaces
  • 6e86904: 8319973: AArch64: Save and restore FPCR in the call stub
  • 04fd17e: 8320410: Reflow markdown in building.md
  • 7f23110: 8319928: Exceptions thrown by cleanup actions should be handled correctly
  • a6098e4: 8320280: RISC-V: Avoid passing t0 as temp register to MacroAssembler::lightweight_lock/unlock
  • 60c8d9c: 8320300: Adjust hs_err output in malloc/mmap error cases
  • 9f6a4a3: 8320386: Remove java/nio/channels/vthread/BlockingChannelOps.java#direct-register from ProblemList
  • db1d823: 8320168: handle setsocktopt return values
  • 6c5e15c: 8316557: Make fields final in 'sun.util' package
  • de51aa1: 8283214: [macos] Screen magnifier does not show the magnified text for JcomboBox
  • ... and 8 more: https://git.openjdk.org/jdk/compare/9902d2eb177072c108933056cba544cc5a34bb54...master

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 master branch, type /integrate in a new comment.

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Nov 17, 2023
@pavelrappo
Copy link
Member Author

/integrate

@openjdk
Copy link

openjdk bot commented Nov 20, 2023

Going to push as commit 3aefd1c.
Since your change was applied there have been 19 commits pushed to the master branch:

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot added the integrated Pull request has been integrated label Nov 20, 2023
@openjdk openjdk bot closed this Nov 20, 2023
@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Nov 20, 2023
@openjdk
Copy link

openjdk bot commented Nov 20, 2023

@pavelrappo Pushed as commit 3aefd1c.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integrated Pull request has been integrated javadoc javadoc-dev@openjdk.org
2 participants