RFR [15] 8247780: Refine the Help page for API Documentation

[Jonathan Gibbons]

All OK, although the use of "prefix" sounds unnatural. "Beginning" might 
be an acceptable
alternative.   You might want to check other sources, but my sense is 
that "prefix" and
"suffix" refer to fragments of words, and not more generally to phrases 
in a sentence or
paragraph.

-- Jon

On 6/19/20 6:21 AM, Pavel Rappo wrote:
> Hello,
>
> Please review the below change for https://bugs.openjdk.java.net/browse/JDK-8247780
>
> -----------------------
> $ hg diff --git
> diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
> --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
> @@ -144,7 +144,7 @@
>       each. These pages may contain six categories:
>   doclet.help.module.intro=\
>       Each module has a page that contains a list of its packages, dependencies on other modules, \
> -    and services, with a summary for each. These page may contain three categories:
> +    and services, with a summary for each. These pages may contain three categories:
>   doclet.help.class_interface.head=\
>       Class or Interface
>   doclet.help.class_interface.intro=\
> @@ -164,7 +164,6 @@
>   doclet.help.class_interface.description=\
>       Class or Interface Description
>   doclet.help.class_interface.summary=\
> -    Each summary entry contains the first sentence from the detailed description for that item. \
>       The summary entries are alphabetical, while the detailed descriptions are in the order they \
>       appear in the source code. This preserves the logical groupings established by the programmer.
>   doclet.help.use.head=\
> @@ -189,7 +188,7 @@
>       hierarchy for only that package.
>   doclet.help.deprecated.body=\
>       The {0} page lists all of the API that have been deprecated. A deprecated API is not \
> -    recommended for use, generally due to improvements, and a replacement API is usually given. \
> +    recommended for use, generally due to shortcomings, and a replacement API is usually given. \
>       Deprecated APIs may be removed in future implementations.
>   doclet.help.index.head=\
>       Index
> @@ -198,9 +197,9 @@
>       and fields, as well as lists of all packages and all classes.
>   doclet.help.serial_form.body=\
>       Each serializable or externalizable class has a description of its serialization fields and \
> -    methods. This information is of interest to re-implementors, not to developers using the API. \
> +    methods. This information is of interest to those who implement rather than use the API. \
>       While there is no link in the navigation bar, you can get to this information by going to any \
> -    serialized class and clicking "Serialized Form" in the "See also" section of the class \
> +    serialized class and clicking "Serialized Form" in the "See Also" section of the class \
>       description.
>   doclet.help.constants.body=\
>       The {0} page lists the static final fields and their values.
> -----------------------
>
>
> @@ -164,7 +164,6 @@
>
> The {@summary} tag makes that description inaccurate as this tag allows to refine the summary boundary. I wanted to improve that description.
>
> I had been fighting with the language for some time when it dawned on me that I might not need to. The only reason that description was there in the first place was probably to introduce the concept of summary before pointing out that summary entries are sorted differently than detailed entries. If so, then that description is nonessential and I propose to drop it altogether; instead of something like
>
> "...Each summary entry consists of a prefix of the detailed description for that item. Typically, the prefix is the first sentence of the detailed description..."
>
> there will be nothing.
>
>
> @@ -189,7 +188,7 @@
>
> If the previous wording were like this
>
> "A deprecated API is not recommended for use, generally due to improvements existing in the provided replacement API."
>
> that is, if there were always a better alternative for a deprecated API, that would make sense. While shortcomings exist in a deprecated API, improvements may only exist in a replacement API, which might be unavailable.
>
>
> @@ -198,9 +197,9 @@
>
> Should it be "implementOrs" or "implementErs"? Is "re-" necessary? I rephrased that sentence such that these questions have gone.
>
> -Pavel
>