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

JDK-8258602: JavaDoc field summary does not indicate final modifier #3716

Closed
wants to merge 1 commit into from

Conversation

hns
Copy link
Member

@hns hns commented Apr 27, 2021

I found that adding the final modifier does not add too much visual noise to the documentation. I didn't find any occurrence where there were more than two modifiers on a member summary (usually either static final or protected final).

On the other hand, I do think the final modifier adds important information about the member. Although this is more true for fields than for other members, for reasons of consistency I decided to show it for all kinds of members except for those where it is not allowed (such as for enums).

To my surprise I also noticed that there weren't any test cases for field summaries, so I added a new test.


Progress

  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change must be properly reviewed

Issue

  • JDK-8258602: JavaDoc field summary does not indicate final modifier

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/3716/head:pull/3716
$ git checkout pull/3716

Update a local copy of the PR:
$ git checkout pull/3716
$ git pull https://git.openjdk.java.net/jdk pull/3716/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 3716

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/3716.diff

@bridgekeeper
Copy link

bridgekeeper bot commented Apr 27, 2021

👋 Welcome back hannesw! 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 Apr 27, 2021
@openjdk
Copy link

openjdk bot commented Apr 27, 2021

@hns 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 Apr 27, 2021
@mlbridge
Copy link

mlbridge bot commented Apr 27, 2021

Webrevs

@dfuch
Copy link
Member

dfuch commented Apr 27, 2021

Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant final keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation. Maybe final should be omitted for members of a final class.

@hns
Copy link
Member Author

hns commented Apr 27, 2021

Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant final keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation. Maybe final should be omitted for members of a final class.

Yes, final will appear as it is used in the source code for method summaries of final classes. In my mind this is acceptable, analogous to both ways being allowed in the source code.

@jonathan-gibbons
Copy link
Contributor

jonathan-gibbons commented Apr 30, 2021

Hi Hannes, out of curiosity - for a final class, will all members (or none) appear final in the generated documentation? Or will it depend on whether a redundant final keyword appears in the code or not? From your code changes, I guess it will be the latter - which makes me wonder whether we want to go that far in the API documentation. Maybe final should be omitted for members of a final class.

Yes, final will appear as it is used in the source code for method summaries of final classes. In my mind this is acceptable, analogous to both ways being allowed in the source code.

This seems surprising and maybe questionable, since in other places, javadoc tries to present a normalized view of modifiers. But, I agree it is in line with existing behavior, and this issue is not about changing that behavior at this time.

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons left a comment

OK, but we might want to think about the pros and cons of normalizing modifiers.

@openjdk
Copy link

openjdk bot commented Apr 30, 2021

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

8258602: JavaDoc field summary does not indicate final modifier

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 94 new commits pushed to the master branch:

  • 51b2188: 8266267: Remove unnecessary jumps in Intel Math Library StubRoutines
  • 2c381e0: 8262376: ReplaceCriticalClassesForSubgraphs.java fails if --with-build-jdk is used
  • 5ecef01: 8266217: ZGC: Improve the -Xlog:gc+init output for NUMA
  • 5d8c1cc: 8255410: Add ChaCha20 and Poly1305 support to SunPKCS11 provider
  • 46b4a14: 8266315: Problem list failing test java/awt/font/TextLayout/LigatureCaretTest.java
  • 42af7da: 8265933: Move Java monitor related fields from class Thread to JavaThread
  • 1afbab6: 8263998: Remove mentions of mc region in comments
  • 51b2fb5: 8266299: ProblemList runtime/stringtable/StringTableCleaningTest.java on linux-aarch64 with ZGC
  • 49d0458: 8266288: assert root method not found in witnessed_reabstraction_in_supers is too strong
  • 01415f3: 8266250: WebSocketTest and WebSocketProxyTest call assertEquals(List<byte[]>, List<byte[]>)
  • ... and 84 more: https://git.openjdk.java.net/jdk/compare/468c847cc8debb885c4442f33e800e1ac0e7012b...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 Apr 30, 2021
@hns
Copy link
Member Author

hns commented Apr 30, 2021

OK, but we might want to think about the pros and cons of normalizing modifiers.

Thanks for the review; I agree we should think about normalizing modifiers.

FWIW, the JLS describes methods in final classes as merely "behaving as if they were final" (8.4.3.3.), so at least technically it is still the modifier that decides. Other constructs are actually declared as implicitly final, with some of them allowing the modifier (such as constants in interfaces) and some not (enums). Here I think we usually show modifiers if they are allowed, although I haven't done a systematic review.

@hns
Copy link
Member Author

hns commented Apr 30, 2021

/integrate

@openjdk openjdk bot closed this Apr 30, 2021
@openjdk openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Apr 30, 2021
@openjdk
Copy link

openjdk bot commented Apr 30, 2021

@hns Since your change was applied there have been 98 commits pushed to the master branch:

  • 276a1bf: 8236671: NullPointerException in JKS keystore
  • e9370a1: 8265761: Font with missed font family name is not properly printed on Windows
  • 3554dc2: 8264395: WB_EnqueueInitializerForCompilation fails with "method holder must be initialized" when called for uninitialized class
  • 4d77171: 8249903: jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java needs to be updated after 8146022 got closed
  • 51b2188: 8266267: Remove unnecessary jumps in Intel Math Library StubRoutines
  • 2c381e0: 8262376: ReplaceCriticalClassesForSubgraphs.java fails if --with-build-jdk is used
  • 5ecef01: 8266217: ZGC: Improve the -Xlog:gc+init output for NUMA
  • 5d8c1cc: 8255410: Add ChaCha20 and Poly1305 support to SunPKCS11 provider
  • 46b4a14: 8266315: Problem list failing test java/awt/font/TextLayout/LigatureCaretTest.java
  • 42af7da: 8265933: Move Java monitor related fields from class Thread to JavaThread
  • ... and 88 more: https://git.openjdk.java.net/jdk/compare/468c847cc8debb885c4442f33e800e1ac0e7012b...master

Your commit was automatically rebased without conflicts.

Pushed as commit 07ecd42.

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

@dfuch
Copy link
Member

dfuch commented Apr 30, 2021

Thanks for the review; I agree we should think about normalizing modifiers.

FWIW, the JLS describes methods in final classes as merely "behaving as if they were final" (8.4.3.3.), so at least technically it is still the modifier that decides. Other constructs are actually declared as implicitly final, with some of them allowing the modifier (such as constants in interfaces) and some not (enums). Here I think we usually show modifiers if they are allowed, although I haven't done a systematic review.

I would be concerned that adding (or removing) a redundant final keyword could be perceived as a specification change if it's reflected in the API documentation. But I am happy for the normalization issue to be revisited later.

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
3 participants