Summary

Clarify in API Documentation that the default implementation of HttpRequest.Builder::build returns an immutable and reusable HttpRequest Object.

Problem

In the API Documentation for HttpRequest.Builder::build, it is not stated or clear what the characteristics of the returned HttpRequest are. It should be stated that the instantiated HttpRequest Object is immutable and can be reused. This is already stated in the class-level API documentation but it will be made more visible by repeating it the documentation of the build method.

Solution

An @implSpec Javadoc Tag was added to the method to describe the immutable and reusable traits of the returned HttpRequest instance.

Specification

Given here is the diff for the changes described above.

In interface HttpRequest.Builder:

         /**
          * Builds and returns an {@link HttpRequest}.
          *
+         * @implSpec This method returns a new {@code HttpRequest} each time it is
+         * invoked. Once built, the {@code HttpRequest} is immutable and can be
+         * sent multiple times.
+         *
          * @return a new {@code HttpRequest}
          * @throws IllegalStateException if a URI has not been set
          */
        public HttpRequest build();