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-8200337: Generalize see and link tags for user-defined anchors #10395

Closed
wants to merge 8 commits into from

Conversation

hns
Copy link
Member

@hns hns commented Sep 22, 2022

Please review a a new feature to allow @link, @linkplain and @see tags to link to arbitrary URI fragments in the generated documentation (including in auxiliary doc-files documentation).

The changes in module jdk.compiler are mostly cleanup changes retained from earlier versions of the patch. The current proposed version uses a very simple change in ReferenceParser to avoid parsing the member name section of the reference when a non-member fragment is encountered.

The implementation introduces a new form of reference with a double hash mark (##) separator. This is a change from the previous implementation which also auto-recognized URI fragments and documentation paths by looking for - characters which are not allowed in member names. This feature was removed upon further consideration because it makes the feature more complex and less recognizable.

Links to auxiliary documentation files follow the same rules. They are recognized by looking for / characters in the fragment name. This means that ordinary id attribute values must not contain /, while auxiliary file paths must contain a / character. Both restrictions should be easy to sustain.

One thing that is difficult for this feature is to provide a good link label if no label is supplied in the tag. In contrast to program element names a fragment name does usually not make a good human readable name. The solution is to use the fragment name as default label text. I expect that the feature will usually be used with a user provided label.


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-8200337: Generalize see and link tags for user-defined anchors
  • JDK-8294195: Generalize see and link tags for user-defined anchors (CSR)

Reviewers

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 10395

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

Using diff file

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

@openjdk openjdk bot added the csr Pull request needs approved CSR before integration label Sep 22, 2022
@bridgekeeper
Copy link

bridgekeeper bot commented Sep 22, 2022

👋 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
Copy link

openjdk bot commented Sep 22, 2022

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

@openjdk openjdk bot added javadoc javadoc-dev@openjdk.org compiler compiler-dev@openjdk.org labels Sep 22, 2022
@jonathan-gibbons
Copy link
Contributor

One thing that is difficult for this feature is to provide a good link label if no label is supplied in the tag.

Generate an error if no label is provided. Now is the time to set the rules.

@openjdk openjdk bot added the rfr Pull request is ready for review label Oct 4, 2022
@mlbridge
Copy link

mlbridge bot commented Oct 4, 2022

Webrevs

@jonathan-gibbons
Copy link
Contributor

One thing that is difficult for this feature is to provide a good link label if no label is supplied in the tag. In contrast to program element names a fragment name does usually not make a good human readable name. The solution is to use the fragment name as default label text. I expect that the feature will usually be used with a user provided label.

There's cognitive dissonance here.

  1. a fragment name does usually not make a good human readable name
  2. the solution is to use the fragment name

At a minimum, we should give a warning, or even an error. We can use the TagletWriterImpl.invalidTagOutput to display something inline in the page. We should consider updating the spec to require that a label is given.

@jonathan-gibbons
Copy link
Contributor

(repeating? after first message was lost...?)

I primarily reviewed the DocCommentParser level of the code.

Removing the allowMember parameter from the reference method seems like a retrograde step, since there are places where the method is called that require a specific kind of reference, such as requiring a type name after @throws.

If anything you should honor the TODO that you deleted there, and upgrade the boolean allowMember parameter into some sort of enum set that allows a caller to specify the kinds of reference that are acceptable in any given syntactic position. After all, the new ## syntax should only be permitted in @see and {@link} nodes.

@hns
Copy link
Member Author

hns commented Oct 17, 2022

The allowMember parameter was never used, so this doesn't change existing behaviour. The validity of @throws references is checked by doclint, where we have much more context (such as whether a type is throwable). We could enforce restrictions on references at the parser level, but it will affect code down the line such as the doclint @throws checks.

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.

Thanks for the new support in the doc-comment-parser for kinds of references. While docent may be able to make better checks, it can also be disabled, so it is good to catch things early where that is possible.

I noticed various additional new/improved doc comments as well: nice!

Check the following question in TestSeeLinkAnchor.java

@openjdk openjdk bot removed the csr Pull request needs approved CSR before integration label Nov 4, 2022
@openjdk
Copy link

openjdk bot commented Nov 4, 2022

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

8200337: Generalize see and link tags for user-defined anchors

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

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 4, 2022
@hns
Copy link
Member Author

hns commented Nov 4, 2022

/integrate

@openjdk
Copy link

openjdk bot commented Nov 4, 2022

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

  • 22347e4: 8277775: Fixup bugids in RemoveDropTargetCrashTest.java - add 4357905
  • 1231682: 8296305: Remove unimplemented deoptimized_wrt_marked_nmethods
  • 3378bfe: 8296224: G1: Remove unnecessary update in VM_G1CollectForAllocation
  • 8ee0f7d: 8296231: Fix MEMFLAGS for CHeapBitMaps
  • bd729e6: 8296380: IGV: Shortcut for quick search not working
  • c116ae7: 8295967: RISC-V: Support negVI/negVL instructions for Vector API
  • 9d3b4ef: 8296108: (tz) Update Timezone Data to 2022f
  • 4d1bc1b: 8296285: test/hotspot/jtreg/compiler/intrinsics/TestFloatIsFinite.java fails after JDK-8280378
  • 0349803: 8295319: pending_cards_at_gc_start doesn't include cards in thread buffers
  • 8f6c048: 8296337: CDS SharedArchiveConsistency tests fail after JDK-8296157
  • ... and 593 more: https://git.openjdk.org/jdk/compare/36c9034ff1274f37969550a3f9239f1bb16a0b25...master

Your commit was automatically rebased without conflicts.

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

openjdk bot commented Nov 4, 2022

@hns Pushed as commit 5622b09.

💡 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
compiler compiler-dev@openjdk.org integrated Pull request has been integrated javadoc javadoc-dev@openjdk.org
Development

Successfully merging this pull request may close these issues.

2 participants