RFR: 8331873: Improve/expand info in `New API In` on Help page

[Hannes Wallnöfer]

On Mon, 13 May 2024 23:08:51 GMT, Jonathan Gibbons <jjg at 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