JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) #8439

jonathan-gibbons · 2022-04-28T02:05:47Z

Please review the code and tests to add support for a new @spec url title tag to javadoc. Note, this does not include any changes to API doc comments to use the new tag in JDK API documentation; that will come later.

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
Change requires a CSR request to be approved

Issues

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
JDK-8264740: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) (CSR)

Reviewers

Hannes Wallnöfer (@hns - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 8439

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

Using diff file

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

…uments referenced from javadocs (OEM spec)

bridgekeeper · 2022-04-28T02:07:32Z

👋 Welcome back jjg! 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 · 2022-04-28T02:09:47Z

@jonathan-gibbons The following labels will be automatically applied to this pull request:

compiler
javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

mlbridge · 2022-04-28T03:05:43Z

Webrevs

pavelrappo

This is nice work. I haven't seen it in detail, but I'm plannig to do so later.

What's the logistics here? There are two interrelated bugs: 6251738 and 8226279. Are you going to add an 8226279 as an issue to this PR (/issue add 8226279)? What about @bug tags in tests? Are they going to mention both issues?

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java

test/langtools/jdk/javadoc/doclet/testConditionalPages/TestConditionalPages.java

test/langtools/jdk/javadoc/doclet/testMetadata/TestMetadata.java

test/langtools/tools/javac/diags/examples/NoTitle.java

test/langtools/tools/javac/diags/examples/NoURI.java

jonathan-gibbons · 2022-05-18T18:18:48Z

This is nice work. I haven't seen it in detail, but I'm plannig to do so later.

What's the logistics here? There are two interrelated bugs: 6251738 and 8226279. Are you going to add an 8226279 as an issue to this PR (/issue add 8226279)? What about @bug tags in tests? Are they going to mention both issues?

For now, I'll track both, here in the PR and in tests. If this becomes impractical, I'll retain the old/original one and close the newer one. The old one described the problem; the newer one described a specific solution, although the actual implementation has move on from that proposed in 8226279.

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java

...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java

test/langtools/tools/javac/diags/examples/NoTitle.java

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java

pavelrappo

I appreciate your perseverance in this review, Jon! A note to self: when we have the next round of review, most URIs will have likely turned into URLs.

remove archaic obsolete build flags

openjdk · 2022-06-09T16:31:50Z

@jonathan-gibbons this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout 6251738.spec-tag-2
git fetch https://git.openjdk.org/jdk master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java

src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java

bridgekeeper · 2022-09-15T02:35:59Z

@jonathan-gibbons This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

hns

All looks very good! The only place that looks suspicious to me is the inherit implementation in SpecTaglet.java, which also seems not to be covered by the test.

I guess the best way to examine the output of the new tag is via test output. I'll have a look at that to see the HTML and CSS in action before giving a thumbs up.

hns · 2022-09-23T13:53:46Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java

+            output.inlineTags = input.isFirstSentence
+                    ? ch.getFirstSentenceTrees(output.holderTag)
+                    : ch.getReference(output.holderTag);
+        }


This implementation seems to be copied from SeeTaglet.java. Is it fully functional in this context? The use of CommentHelper.getReference looks suspicious to me.

Thanks for the comment; I'll investigate

Good catch;

Yes, the use of getReference is indeed questionable, given its implementation, which is specific to @see. Given ongoing recent work, it's also not clear that the @spec tag should be inheritable.

For now, I'll change it to getTags, pending discussions on whether the tag should be inheritable.

With the latest update, toy examples show that tag inherits works as expected, as least as far as parity with @see.

hns

I don't know if you want to further discuss inheritability of the new tag, but the code looks good to me. I've also looked at the generated output and it also looks good.

openjdk · 2022-09-26T12:35:27Z

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

6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)

Reviewed-by: hannesw

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

2be3158: 4797982: Setting negative size of JSplitPane divider leads to unexpected results.
050eebf: 8294245: Make Compile::print_inlining_stream stack allocated
91a23d7: 8294142: make test should report only on executed tests
169a5d4: 8294193: Files.createDirectories throws FileAlreadyExistsException for a symbolic link whose target is an existing directory
3675f4c: 8293252: Shenandoah: ThreadMXBean synchronizer tests crash with aggressive heuristics
543851d: 8289607: Change hotspot/jtreg tests to not use Thread.suspend/resume
e2f8251: 8293618: x86: Wrong code generation in class Assembler
6ecd081: 8294270: make test passes awkward -status:-status:error,fail to jtreg
eca9749: 8288325: [windows] Actual and Preferred Size of AWT Non-resizable frame are different
2e20e7e: 8294271: Remove use of ThreadDeath from make utilities
... and 28 more: https://git.openjdk.org/jdk/compare/2283c3244f4fe475593d8a53613b5a3228bec356...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.

jonathan-gibbons · 2022-09-26T21:03:51Z

I don't know if you want to further discuss inheritability of the new tag, but the code looks good to me. I've also looked at the generated output and it also looks good.

I think of @spec as a highly specialized form of @see with the significant side effect of generating an extra summary page. So, I'm happy/OK that the support for inheritability is on a par with @see. It's not great, since it will only inherit one tag (!!) and you cannot specify which one, but the code is sufficiently similar so when we fix one (later) we should be able to easily fix the other.

For reference, I note there is an umbrella issue covering doc inheritance:
JDK-8285368

jonathan-gibbons · 2022-09-26T21:26:47Z

/integrate

openjdk · 2022-09-26T21:28:51Z

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

aca4276: 8294379: Missing comma after copyright year
1f521a1: 8225012: sanity/client/SwingSet/src/ToolTipDemoTest.java fails on Windows
5ae6bc2: 8234262: Unmask SIGQUIT in a child process
968af74: 8293567: AbstractSplittableWithBrineGenerator: salt has digits that duplicate the marker
36b61c5: 8293872: Make runtime/Thread/ThreadCountLimit.java more robust
2be3158: 4797982: Setting negative size of JSplitPane divider leads to unexpected results.
050eebf: 8294245: Make Compile::print_inlining_stream stack allocated
91a23d7: 8294142: make test should report only on executed tests
169a5d4: 8294193: Files.createDirectories throws FileAlreadyExistsException for a symbolic link whose target is an existing directory
3675f4c: 8293252: Shenandoah: ThreadMXBean synchronizer tests crash with aggressive heuristics
... and 33 more: https://git.openjdk.org/jdk/compare/2283c3244f4fe475593d8a53613b5a3228bec356...master

Your commit was automatically rebased without conflicts.

openjdk · 2022-09-26T21:29:07Z

@jonathan-gibbons Pushed as commit b88ee1e.

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

jonathan-gibbons added 2 commits April 27, 2022 18:56

JDK-6251738: Want a top-level summary page that itemizes all spec doc…

dd5720e

…uments referenced from javadocs (OEM spec)

fix whitespace

105864d

openjdk bot added javadoc javadoc-dev@openjdk.org compiler compiler-dev@openjdk.org labels Apr 28, 2022

fix whitespace and position of HtmlStyle.refList

c4fd991

openjdk bot added the rfr Pull request is ready for review label Apr 28, 2022

pavelrappo reviewed May 3, 2022

View reviewed changes

jonathan-gibbons added 2 commits May 18, 2022 10:20

merge with upstream/master

af1a716

fix merge issues

2992b6b

address review feedback

47e7179

pavelrappo reviewed May 24, 2022

View reviewed changes

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

8d98f6e

pavelrappo reviewed May 24, 2022

View reviewed changes

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java Outdated Show resolved Hide resolved

openjdk bot added the csr Pull request needs approved CSR before integration label May 24, 2022

pavelrappo reviewed May 24, 2022

View reviewed changes

jonathan-gibbons added 3 commits May 24, 2022 14:55

address review feedback

acd43de

more URI -> URL

b03bbb6

fix copyright dates

c24c02a

remove archaic obsolete build flags

openjdk bot added the merge-conflict Pull request has merge conflict with target branch label Jun 9, 2022

Merge with upstream/master

8697cac

openjdk bot removed the merge-conflict Pull request has merge conflict with target branch label Jun 13, 2022

jonathan-gibbons added 4 commits June 22, 2022 08:43

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

7f16705

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

73c0ba6

Updates for latest repo

2654081

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

f6280e7

jddarcy reviewed Jun 29, 2022

View reviewed changes

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTree.java Outdated Show resolved Hide resolved

jddarcy reviewed Jun 29, 2022

View reviewed changes

src/jdk.compiler/share/classes/com/sun/source/util/SimpleDocTreeVisitor.java Outdated Show resolved Hide resolved

openjdk bot removed the csr Pull request needs approved CSR before integration label Jun 29, 2022

jonathan-gibbons added 5 commits July 6, 2022 09:13

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

f7a953a

Update @SInCE tags

f0ce193

Merge with upstream/master

f84ee08

Fix typo and merge error

214b924

Merge with upstream/master

e8fe51b

jonathan-gibbons added 2 commits September 21, 2022 17:09

Merge remote-tracking branch 'upstream/master' into 6251738.spec-tag-2

2f0b917

Fix merge issue

be7510e

hns reviewed Sep 23, 2022

View reviewed changes

jonathan-gibbons added 2 commits September 23, 2022 11:19

Address review comment

9730192

Update DPrinter

30a4396

hns approved these changes Sep 26, 2022

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Sep 26, 2022

openjdk bot added the integrated Pull request has been integrated label Sep 26, 2022

openjdk bot closed this Sep 26, 2022

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Sep 26, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) #8439

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) #8439

jonathan-gibbons commented Apr 28, 2022 •

edited by openjdk bot

Loading

bridgekeeper bot commented Apr 28, 2022

openjdk bot commented Apr 28, 2022

mlbridge bot commented Apr 28, 2022 •

edited

Loading

pavelrappo left a comment

jonathan-gibbons commented May 18, 2022

pavelrappo left a comment

openjdk bot commented Jun 9, 2022

bridgekeeper bot commented Sep 15, 2022

hns left a comment

hns Sep 23, 2022

jonathan-gibbons Sep 23, 2022

jonathan-gibbons Sep 23, 2022 •

edited

Loading

jonathan-gibbons Sep 23, 2022

jonathan-gibbons Sep 23, 2022

hns left a comment

openjdk bot commented Sep 26, 2022

jonathan-gibbons commented Sep 26, 2022 •

edited

Loading

jonathan-gibbons commented Sep 26, 2022

openjdk bot commented Sep 26, 2022

openjdk bot commented Sep 26, 2022

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) #8439

JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) #8439

Conversation

jonathan-gibbons commented Apr 28, 2022 • edited by openjdk bot Loading

Progress

Issues

Reviewers

Reviewing

bridgekeeper bot commented Apr 28, 2022

openjdk bot commented Apr 28, 2022

mlbridge bot commented Apr 28, 2022 • edited Loading

Webrevs

pavelrappo left a comment

Choose a reason for hiding this comment

jonathan-gibbons commented May 18, 2022

pavelrappo left a comment

Choose a reason for hiding this comment

openjdk bot commented Jun 9, 2022

bridgekeeper bot commented Sep 15, 2022

hns left a comment

Choose a reason for hiding this comment

hns Sep 23, 2022

Choose a reason for hiding this comment

jonathan-gibbons Sep 23, 2022

Choose a reason for hiding this comment

jonathan-gibbons Sep 23, 2022 • edited Loading

Choose a reason for hiding this comment

jonathan-gibbons Sep 23, 2022

Choose a reason for hiding this comment

jonathan-gibbons Sep 23, 2022

Choose a reason for hiding this comment

hns left a comment

Choose a reason for hiding this comment

openjdk bot commented Sep 26, 2022

jonathan-gibbons commented Sep 26, 2022 • edited Loading

jonathan-gibbons commented Sep 26, 2022

openjdk bot commented Sep 26, 2022

openjdk bot commented Sep 26, 2022

jonathan-gibbons commented Apr 28, 2022 •

edited by openjdk bot

Loading

mlbridge bot commented Apr 28, 2022 •

edited

Loading

jonathan-gibbons Sep 23, 2022 •

edited

Loading

jonathan-gibbons commented Sep 26, 2022 •

edited

Loading