RFR: 8327991: Improve HttpClient documentation with regard to reclaiming resources [v3]

[Michael McMahon]

On Sat, 16 Mar 2024 22:19:25 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> Please find here a doc-only change that tries to better document how resources allocated by the HttpClient are reclaimed.
>> The `@implNote` in the HttpClient class level API documentation is extended to document what happens if you don't explicitly close the HttpClient. The note is refactored to introduce the notion of streaming or publishing bodies. BodySubscribers and BodyHandlers now have links that link back to the HttpClient API note, as well as identifying methods that return publishing or streaming body implementations.
>
> Daniel Fuchs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Minor tweak WRT calling CompletableFuture::cancel

src/java.net.http/share/classes/java/net/http/HttpClient.java line 139:

> 137:  *  <p id="streaming">
> 138:  *  The HttpClient {@link BodyHandlers} and {@link BodySubscribers}
> 139:  *  API provide some {@linkplain BodySubscribers##streaming-body streaming

Suggestion:

 *  The {@link BodyHandlers} and {@link BodySubscribers}
 *  classes provide some {@linkplain BodySubscribers##streaming-body streaming

src/java.net.http/share/classes/java/net/http/HttpResponse.java line 1244:

> 1242:          *
> 1243:          * @return a {@linkplain HttpClient##streaming streaming body subscriber}
> 1244:          *         that streams the response body as an {@link InputStream}.

Suggestion:

         *         which streams the response body as an {@link InputStream}.

src/java.net.http/share/classes/java/net/http/HttpResponse.java line 1269:

> 1267:          *
> 1268:          * @param charset the character set to use when converting bytes to characters
> 1269:          * @return a {@linkplain HttpClient##streaming streaming body subscriber} that streams

Suggestion:

         * @return a {@linkplain HttpClient##streaming streaming body subscriber} which streams

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18270#discussion_r1532490866
PR Review Comment: https://git.openjdk.org/jdk/pull/18270#discussion_r1532499902
PR Review Comment: https://git.openjdk.org/jdk/pull/18270#discussion_r1532501773