On Tue, 28 May 2024 19:57:32 GMT, Jonathan Gibbons <j...@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
