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

[Hannes Wallnöfer]

On Tue, 28 May 2024 19:57:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

I still think that reversing the sentence as proposed in my comment above would make the intent clearer. I think the "normally" is ok in that order, so I re-added it:

"In those situations where a member was added after the initial introduction of the enclosing class or interface, the detail of the member normally 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?
>
> The hard bit is that those pages may not always be present, depending on the command-line options...

I still think this is not ideal ("Some summary pages" then followed by "introduced or deprecated"), but it shouldn't be a show-stopper either. It's better to have this covered, even if the wording is not perfect.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1866082523
PR Review Comment: https://git.openjdk.org/jdk/pull/19222#discussion_r1866086631