RFR: 8281223: Improve the API documentation of HttpRequest.Builder::build to state that the default implementation provided by the JDK returns immutable objects.

[Conor Cleary]

On Tue, 15 Feb 2022 15:04:12 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> As described in the title, this is a simple change to the `HttpRequest.Builder::build` method to highlight that an immutable and reusable instance of an `HttpRequest` is created when this method is invoked. This is done by adding an `@implSpec` Javadoc Tag (details on `@implSpec` given [here](https://openjdk.java.net/jeps/8068562)). 
>> 
>> The detail added under the `@implSpec` Tag is similar to that provided at the interface-level Javadoc for Builder.
>> 
>> Please also review the CSR for this change: https://bugs.openjdk.java.net/browse/JDK-8281833
>
> src/java.net.http/share/classes/java/net/http/HttpRequest.java line 297:
> 
>> 295:          * @implSpec Returns a new {@code HttpRequest} each time it is
>> 296:          * invoked. Once built, the HttpRequest is immutable and can be
>> 297:          * sent multiple times.
> 
> Looks fine to me. Maybe "This method returns ..." would more appropriate for an `@implSpec`. Also the second mention of `HttpRequest` should also have `{@code }` around it.

Agree with both statements. "This method returns..." adds additional clarity and the additional {@code } was left out in error. Will correct now.

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

PR: https://git.openjdk.java.net/jdk/pull/7479