On Mon, 13 May 2024 23:08:51 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> 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 `@since` tags.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
line 381:
> 379: # The title for the Javadoc Search Specification
> 380: doclet.help.search.spec.title=Javadoc Search Specification
> 381: doclet.help.releases.head=Release Details
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)".
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
line 389:
> 387: include the release in which the member was introduced, in those
> situations \
> 388: where the member was added after the initial introduction of the \
> 389: enclosing class or interface.
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.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
line 392:
> 390: doclet.help.releases.body.refer=\
> 391: Some summary pages allow you to filter the contents of the page
> according to \
> 392: the release in which the declaration was introduced or deprecated.
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?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1613689324
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1613686145
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1613678814
