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