8331873: Improve/expand info in New API In on Help page
#19222
Conversation
|
👋 Welcome back jjg! A progress list of the required criteria for merging this PR into |
|
❗ This change is not yet ready to be integrated. |
|
@jonathan-gibbons The following label will be automatically applied to this pull request:
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. |
jonathan-gibbons
changed the title
New API In on Help page.New API In on Help page
| enclosing class or interface. | ||
| doclet.help.releases.body.refer=\ | ||
| Some summary pages allow you to filter the contents of the page according to \ | ||
| the release in which the declaration was introduced or deprecated. |
There was a problem hiding this comment.
We already have help sections for New and Deprecated API, and the paragraph is somewhat vague. I think we should at least mention the summary pages by name ("New API", "Deprecated API"). Maybe link to the pages or help sections?
There was a problem hiding this comment.
The hard bit is that those pages may not always be present, depending on the command-line options...
| The details for each member of a class or interface normally \ | ||
| include the release in which the member was introduced, in those situations \ | ||
| where the member was added after the initial introduction of the \ | ||
| enclosing class or interface. |
There was a problem hiding this comment.
I think "normally" is confusing here, because a member being added in a later release is not necessary the "normal" case. How about reversing the sentence to make it immediately clear what we're talking about?
In those situations where a member was added after the initial introduction of the enclosing class or interface, the detail of the member includes the release in which it was introduced.
There was a problem hiding this comment.
Yeah, I agree the use of normally here could be seen as ambiguous. The comma on line 387 doesn't help.
| @@ -378,6 +378,18 @@ doclet.help.search.refer=Refer to the {0} for a full description of search featu | |||
| doclet.help.search.spec.url=https://docs.oracle.com/en/java/javase/{0}/docs/specs/javadoc/javadoc-search-spec.html | |||
| # The title for the Javadoc Search Specification | |||
| doclet.help.search.spec.title=Javadoc Search Specification | |||
| doclet.help.releases.head=Release Details | |||
There was a problem hiding this comment.
The subtitle "Release Details" surprised me, because it seems to suggest "details about releases", while it is more like "release information (contained in API details)".
There was a problem hiding this comment.
I'll look to see what I can improve
Please review a relatively simple update to the generated Help page, as part of the ongoing campaign to improve the documentation around the overall use of
@sincetags.Progress
Issue
New API Inon Help page (Enhancement - P4)Reviewing
Using
gitCheckout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/19222/head:pull/19222$ git checkout pull/19222Update a local copy of the PR:
$ git checkout pull/19222$ git pull https://git.openjdk.org/jdk.git pull/19222/headUsing Skara CLI tools
Checkout this PR locally:
$ git pr checkout 19222View PR using the GUI difftool:
$ git pr show -t 19222Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/19222.diff
Webrev
Link to Webrev Comment