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

[hns]

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

• Jonathan Gibbons (@jonathan-gibbons - Reviewer)

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]

👋 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]

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

[mlbridge]

Webrevs

• 01: Full - Incremental (a6a9d202)
• 00: Full (074b7326)

[dfuch]

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]

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]

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.

[jonathan-gibbons]

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

[openjdk]

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

[hns]

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]

/integrate

[openjdk]

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

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.