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

[Jonathan Gibbons]

On Fri, 24 May 2024 15:47:02 GMT, Hannes Wallnöfer <hannesw 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)".

I'll look to see what I can improve

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

Yeah, I agree the use of `normally` here could be seen as ambiguous. The comma on line 387 doesn't help.

> 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?

The hard bit is that those pages may not always be present, depending on the command-line options...

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1617825827
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1617824737
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1617826901