[client] Update Javadocs (#643)

* update javadocs

* Update HttpAsyncResponse.java

---------

Co-authored-by: Rob Bygrave <robin.bygrave@gmail.com>

Author: SentryMan

http-client/src/main/java/io/avaje/http/client/AuthToken.java

@@ -5,28 +5,26 @@
 
 /**
  * Represents an Authorization Bearer token that can be held on the context.
- * <p>
- * Typically the token will be valid for a period and then expire.
  */
 public interface AuthToken {
 
   /**
-   * Return the Authorization bearer token.
+   * The Authorization bearer token.
    */
   String token();
 
   /**
-   * Return true if the token has expired or is no longer valid.
+   * Whether the token has expired or no longer valid.
    */
   boolean isExpired();
 
   /**
-   * Return the duration until expiry.
+   * Duration until expiration.
    */
   Duration expiration();
 
   /**
-   * Create an return a AuthToken with the given token and time it is valid until.
+   * Create an AuthToken with the given token and when it expires.
    */
   static AuthToken of(String token, Instant validUntil) {
     return new Basic(token, validUntil);

http-client/src/main/java/io/avaje/http/client/AuthTokenProvider.java

@@ -1,7 +1,7 @@
 package io.avaje.http.client;
 
 /**
- * Use to obtain an Authorization bearer token that is expected to be used.
+ * Use to obtain an Authorization bearer token used for authenticated requests.
  *
  * <pre>{@code
  *
@@ -33,7 +33,7 @@ public interface AuthTokenProvider {
   /**
    * Obtain a new Authorization token.
    *
-   * @param tokenRequest A new request to obtain an Authorisation token
+   * @param tokenRequest A new request to obtain an Authorization token
    */
   AuthToken obtainToken(HttpClientRequest tokenRequest);
 

http-client/src/main/java/io/avaje/http/client/BodyAdapter.java

@@ -3,22 +3,18 @@
 import java.lang.reflect.Type;
 import java.util.List;
 
-/**
- * Adaptor between beans and content of a request or response.
- * <p>
- * Typically converts between beans as JSON content.
- */
+/** Adapter between beans and content of a request or response. */
 public interface BodyAdapter {
 
   /**
-   * Return a BodyWriter to write beans of this type as request content.
+   * BodyWriter to write beans of this type as request content.
    *
    * @param type The type of the bean this writer is for
    */
   <T> BodyWriter<T> beanWriter(Class<?> type);
 
   /**
-   * Return a BodyWriter to write beans of this type as request content.
+   * BodyWriter to write beans of this type as request content.
    *
    * @param type The type of the bean this writer is for
    */
@@ -27,32 +23,32 @@ default <T> BodyWriter<T> beanWriter(Type type) {
   }
 
   /**
-   * Return a BodyReader to read response content and convert to a bean.
+   * BodyReader to read response content and convert to a bean.
    *
-   * @param type The bean type to convert the content to.
+   * @param type type to convert the content to.
    */
   <T> BodyReader<T> beanReader(Class<T> type);
 
   /**
-   * Return a BodyReader to read response content and convert to a bean.
+   * BodyReader to read response content and convert to a bean.
    *
-   * @param type The bean type to convert the content to.
+   * @param type type to convert the content to.
    */
   default <T> BodyReader<T> beanReader(Type type) {
     throw new UnsupportedOperationException("java.lang.reflect.Type is not supported for this adapter");
   }
 
   /**
-   * Return a BodyReader to read response content and convert to a list of beans.
+   * BodyReader to read response content and convert to a list of beans.
    *
-   * @param type The bean type to convert the content to.
+   * @param type type to convert the content to.
    */
   <T> BodyReader<List<T>> listReader(Class<T> type);
 
   /**
-   * Return a BodyReader to read response content and convert to a list of beans.
+   * BodyReader to read response content and convert to a list of beans.
    *
-   * @param type The bean type to convert the content to.
+   * @param type type to convert the content to.
    */
   default <T> BodyReader<List<T>> listReader(Type type) {
     throw new UnsupportedOperationException("java.lang.reflect.Type is not supported for this adapter");

http-client/src/main/java/io/avaje/http/client/BodyContent.java

@@ -1,7 +1,7 @@
 package io.avaje.http.client;
 
 /**
- * Content of request or response body used for adapting to beans.
+ * Content of request or response body.
  * <p>
  * This is not used for streaming content.
  */

http-client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java

@@ -62,44 +62,38 @@
 public interface HttpAsyncResponse {
 
   /**
-   * Process the response with check for 200 range status code
-   * returning as {@literal HttpResponse<Void>}.
-   * <p>
-   * Unlike {@link #asDiscarding()} this request will read any response
-   * content as bytes with the view that the response content can be
-   * an error message that could be read via for example
-   * {@link HttpException#bean(Class)}.
-   * <p>
-   * Will throw an HttpException if the status code is in the
-   * error range allowing the caller to access the error message
-   * body via for example {@link HttpException#bean(Class)}
-   * <p>
-   * This is intended to be used for POST, PUT, DELETE requests
-   * where the caller is only interested in the response body
-   * when an error occurs (status code not in 200 range).
-   *
-   * <pre>{@code
-   *
-   *   client.request()
-   *       .path("hello/world")
-   *       .GET()
-   *       .async().asVoid()
-   *       .whenComplete((hres, throwable) -> {
-   *
-   *         if (throwable != null) {
+   * Process the response with check for 200 range status code returning as {@literal
+   * HttpResponse<Void>}.
    *
-   *           // if throwable.getCause() is a HttpException for status code >= 300
-   *           HttpException httpException = (HttpException) throwable.getCause();
-   *           int status = httpException.statusCode();
+   * <p>Unlike {@link #asDiscarding()}, this request will read any response content as bytes with
+   * the view that the response content can be an error message that could be read via for example
+   * {@link HttpException#bean(Class)}.
    *
-   *           // convert json error response body to a bean
-   *           ErrorResponse errorResponse = httpException.bean(ErrorResponse.class);
-   *           ...
-   *         } else {
-   *           int statusCode = hres.statusCode();
-   *           ...
-   *         }
-   *       });
+   * @throws HttpException if the status code is in the error range allowing the caller to access
+   *     the error message body via for example {@link HttpException#bean(Class)}
+   *     <p>This is intended to be used for POST, PUT, DELETE requests where the caller is only
+   *     interested in the response body when an error occurs (status code not in 200 range).
+   *     <pre>{@code
+   * client.request()
+   *     .path("hello/world")
+   *     .GET()
+   *     .async().asVoid()
+   *     .whenComplete((hres, throwable) -> {
+   *
+   *       if (throwable != null) {
+   *
+   *         // if throwable.getCause() is a HttpException for status code >= 300
+   *         HttpException httpException = (HttpException) throwable.getCause();
+   *         int status = httpException.statusCode();
+   *
+   *         // convert json error response body to a bean
+   *         ErrorResponse errorResponse = httpException.bean(ErrorResponse.class);
+   *         ...
+   *       } else {
+   *         int statusCode = hres.statusCode();
+   *         ...
+   *       }
+   *     });
    *
    * }</pre>
    */

http-client/src/main/java/module-info.java

@@ -1,3 +1,24 @@
+/**
+ * Provides a HTTP client backed by java's built in {@link java.net.http.HttpClient} with support for adapting body content
+ * (like JSON) to java types.
+ * <p>
+ * Uses the Java http client
+ *
+ * <pre>{@code
+ *
+ *   HttpClient client = HttpClient.builder()
+ *       .baseUrl("http://localhost:8080")
+ *       .bodyAdapter(new JacksonBodyAdapter())
+ *       .build();
+ *
+ *  HelloDto dto = client.request()
+ *       .path("hello")
+ *       .queryParam("say", "Whats up")
+ *       .GET()
+ *       .bean(HelloDto.class);
+ *
+ * }</pre>
+ */
 module io.avaje.http.client {
 
   uses io.avaje.http.client.HttpClient.GeneratedComponent;