Docs fixes/clarity improvements (#1594)

Thanks a lo, it really helps!

Author: n-miles

Diff for: README.md

@@ -5,7 +5,7 @@ Follow [@AsyncHttpClient](https://twitter.com/AsyncHttpClient) on Twitter.
 The AsyncHttpClient (AHC) library allows Java applications to easily execute HTTP requests and asynchronously process HTTP responses.
 The library also supports the WebSocket Protocol.
 
-It's built on top of [Netty](https://github.com/netty/netty). I's currently compiled on Java 8 but runs on Java 9 too.
+It's built on top of [Netty](https://github.com/netty/netty). It's currently compiled on Java 8 but runs on Java 9 too.
 
 ## Installation
 
@@ -159,7 +159,7 @@ See `AsyncCompletionHandler` implementation as an example.
 
 The below sample just capture the response status and skips processing the response body chunks.
 
-Note that returning `ABORT` closed the underlying connection.
+Note that returning `ABORT` closes the underlying connection.
 
 ```java
 import static org.asynchttpclient.Dsl.*;
@@ -196,7 +196,7 @@ Integer statusCode = whenStatusCode.get();
 
 #### Using Continuations
 
-`ListenableFuture` has a `toCompletableFuture` that returns a `CompletableFuture`.
+`ListenableFuture` has a `toCompletableFuture` method that returns a `CompletableFuture`.
 Beware that canceling this `CompletableFuture` won't properly cancel the ongoing request.
 There's a very good chance we'll return a `CompletionStage` instead in the next release.
 
@@ -244,7 +244,7 @@ WebSocket websocket = c.prepareGet("ws://demos.kaazing.com/echo")
 
 ## Reactive Streams
 
-AsyncHttpClient has build in support for reactive streams.
+AsyncHttpClient has built-in support for reactive streams.
 
 You can pass a request body as a `Publisher<ByteBuf>` or a `ReactiveStreamsBodyGenerator`.
 
@@ -289,7 +289,7 @@ Keep up to date on the library development by joining the Asynchronous HTTP Clie
 
 Of course, Pull Requests are welcome.
 
-Here a the few rules we'd like you to respect if you do so:
+Here are the few rules we'd like you to respect if you do so:
 
 * Only edit the code related to the suggested change, so DON'T automatically format the classes you've edited.
 * Use IntelliJ default formatting rules.

Diff for: client/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java

@@ -24,7 +24,7 @@
 /**
  * An {@link AsyncHandler} augmented with an {@link #onCompleted(Response)}
  * convenience method which gets called when the {@link Response} processing is
- * finished. This class also implement the {@link ProgressAsyncHandler}
+ * finished. This class also implements the {@link ProgressAsyncHandler}
  * callback, all doing nothing except returning
  * {@link org.asynchttpclient.AsyncHandler.State#CONTINUE}
  *

Diff for: client/src/main/java/org/asynchttpclient/AsyncHandler.java

@@ -37,9 +37,9 @@
  * </ol>
  * <br>
  * Returning a {@link AsyncHandler.State#ABORT} from any of those callback methods will interrupt asynchronous response
- * processing, after that only {@link #onCompleted()} is going to be called.
+ * processing. After that, only {@link #onCompleted()} is going to be called.
  * <br>
- * AsyncHandler aren't thread safe, hence you should avoid re-using the same instance when doing concurrent requests.
+ * AsyncHandlers aren't thread safe. Hence, you should avoid re-using the same instance when doing concurrent requests.
  * As an example, the following may produce unexpected results:
  * <blockquote><pre>
  *   AsyncHandler ah = new AsyncHandler() {....};
@@ -49,9 +49,10 @@
  * </pre></blockquote>
  * It is recommended to create a new instance instead.
  * <p>
- * Do NOT perform any blocking operation in there, typically trying to send another request and call get() on its future.
+ * Do NOT perform any blocking operations in any of these methods. A typical example would be trying to send another
+ * request and calling get() on its future.
  * There's a chance you might end up in a dead lock.
- * If you really to perform blocking operation, executed it in a different dedicated thread pool.
+ * If you really need to perform a blocking operation, execute it in a different dedicated thread pool.
  *
  * @param <T> Type of object returned by the {@link java.util.concurrent.Future#get}
  */
@@ -142,6 +143,8 @@ default void onHostnameResolutionSuccess(String name, List<InetSocketAddress> ad
   default void onHostnameResolutionFailure(String name, Throwable cause) {
   }
 
+  // ////////////// TCP CONNECT ////////
+
   /**
    * Notify the callback when trying to open a new connection.
    * <p>
@@ -152,8 +155,6 @@ default void onHostnameResolutionFailure(String name, Throwable cause) {
   default void onTcpConnectAttempt(InetSocketAddress remoteAddress) {
   }
 
-  // ////////////// TCP CONNECT ////////
-
   /**
    * Notify the callback after a successful connect
    *
@@ -174,14 +175,14 @@ default void onTcpConnectSuccess(InetSocketAddress remoteAddress, Channel connec
   default void onTcpConnectFailure(InetSocketAddress remoteAddress, Throwable cause) {
   }
 
+  // ////////////// TLS ///////////////
+
   /**
    * Notify the callback before TLS handshake
    */
   default void onTlsHandshakeAttempt() {
   }
 
-  // ////////////// TLS ///////////////
-
   /**
    * Notify the callback after the TLS was successful
    */
@@ -196,14 +197,14 @@ default void onTlsHandshakeSuccess() {
   default void onTlsHandshakeFailure(Throwable cause) {
   }
 
+  // /////////// POOLING /////////////
+
   /**
    * Notify the callback when trying to fetch a connection from the pool.
    */
   default void onConnectionPoolAttempt() {
   }
 
-  // /////////// POOLING /////////////
-
   /**
    * Notify the callback when a new connection was successfully fetched from the pool.
    *
@@ -220,6 +221,8 @@ default void onConnectionPooled(Channel connection) {
   default void onConnectionOffer(Channel connection) {
   }
 
+  // //////////// SENDING //////////////
+
   /**
    * Notify the callback when a request is being written on the channel. If the original request causes multiple requests to be sent, for example, because of authorization or
    * retry, it will be notified multiple times.
@@ -229,8 +232,6 @@ default void onConnectionOffer(Channel connection) {
   default void onRequestSend(NettyRequest request) {
   }
 
-  // //////////// SENDING //////////////
-
   /**
    * Notify the callback every time a request is being retried.
    */

Diff for: client/src/main/java/org/asynchttpclient/AsyncHttpClient.java

@@ -21,15 +21,15 @@
 import java.util.function.Predicate;
 
 /**
- * This class support asynchronous and synchronous HTTP request.
+ * This class support asynchronous and synchronous HTTP requests.
  * <br>
- * To execute synchronous HTTP request, you just need to do
+ * To execute a synchronous HTTP request, you just need to do
  * <blockquote><pre>
  *    AsyncHttpClient c = new AsyncHttpClient();
  *    Future&lt;Response&gt; f = c.prepareGet(TARGET_URL).execute();
  * </pre></blockquote>
  * <br>
- * The code above will block until the response is fully received. To execute asynchronous HTTP request, you
+ * The code above will block until the response is fully received. To execute an asynchronous HTTP request, you
  * create an {@link AsyncHandler} or its abstract implementation, {@link AsyncCompletionHandler}
  * <br>
  * <blockquote><pre>
@@ -48,7 +48,7 @@
  *      &#125;);
  *      Response response = f.get();
  *
- *      // We are just interested to retrieve the status code.
+ *      // We are just interested in retrieving the status code.
  *     Future&lt;Integer&gt; f = c.prepareGet(TARGET_URL).execute(new AsyncCompletionHandler&lt;Integer&gt;() &#123;
  *
  *          &#64;Override
@@ -63,10 +63,10 @@
  *      &#125;);
  *      Integer statusCode = f.get();
  * </pre></blockquote>
- * The {@link AsyncCompletionHandler#onCompleted(Response)} will be invoked once the http response has been fully read, which include
- * the http headers and the response body. Note that the entire response will be buffered in memory.
+ * The {@link AsyncCompletionHandler#onCompleted(Response)} method will be invoked once the http response has been fully read.
+ * The {@link Response} object includes the http headers and the response body. Note that the entire response will be buffered in memory.
  * <br>
- * You can also have more control about the how the response is asynchronously processed by using a {@link AsyncHandler}
+ * You can also have more control about the how the response is asynchronously processed by using an {@link AsyncHandler}
  * <blockquote><pre>
  *      AsyncHttpClient c = new AsyncHttpClient();
  *      Future&lt;String&gt; f = c.prepareGet(TARGET_URL).execute(new AsyncHandler&lt;String&gt;() &#123;
@@ -106,8 +106,8 @@
  *
  *      String bodyResponse = f.get();
  * </pre></blockquote>
- * You can asynchronously process the response status,headers and body and decide when to
- * stop the processing the response by returning a new {@link AsyncHandler.State#ABORT} at any moment.
+ * You can asynchronously process the response status, headers and body and decide when to
+ * stop processing the response by returning a new {@link AsyncHandler.State#ABORT} at any moment.
  *
  * This class can also be used without the need of {@link AsyncHandler}.
  * <br>
@@ -125,8 +125,8 @@
  *      Response r = f.get();
  * </pre></blockquote>
  * <br>
- * An instance of this class will cache every HTTP 1.1 connections and close them when the {@link DefaultAsyncHttpClientConfig#getReadTimeout()}
- * expires. This object can hold many persistent connections to different host.
+ * An instance of this class will cache every HTTP 1.1 connection and close them when the {@link DefaultAsyncHttpClientConfig#getReadTimeout()}
+ * expires. This object can hold many persistent connections to different hosts.
  */
 public interface AsyncHttpClient extends Closeable {
 
@@ -138,7 +138,7 @@ public interface AsyncHttpClient extends Closeable {
   boolean isClosed();
 
   /**
-   * Set default signature calculator to use for requests build by this client instance
+   * Set default signature calculator to use for requests built by this client instance
    *
    * @param signatureCalculator a signature calculator
    * @return {@link RequestBuilder}

Diff for: client/src/main/java/org/asynchttpclient/RequestBuilder.java

@@ -18,7 +18,7 @@
 import static org.asynchttpclient.util.HttpConstants.Methods.GET;
 
 /**
- * Builder for a {@link Request}. Warning: mutable and not thread-safe! Beware that it holds a reference on the Request instance it builds, so modifying the builder will modify the
+ * Builder for a {@link Request}. Warning: mutable and not thread-safe! Beware that it holds a reference to the Request instance it builds, so modifying the builder will modify the
  * request even after it has been built.
  */
 public class RequestBuilder extends RequestBuilderBase<RequestBuilder> {

Diff for: client/src/main/java/org/asynchttpclient/Response.java

@@ -160,16 +160,16 @@ public interface Response {
   boolean hasResponseBody();
 
   /**
-   * Get remote address client initiated request to.
+   * Get the remote address that the client initiated the request to.
    *
-   * @return remote address client initiated request to, may be {@code null} if asynchronous provider is unable to provide the remote address
+   * @return The remote address that the client initiated the request to. May be {@code null} if asynchronous provider is unable to provide the remote address
    */
   SocketAddress getRemoteAddress();
 
   /**
-   * Get local address client initiated request from.
+   * Get the local address that the client initiated the request from.
    *
-   * @return local address client initiated request from, may be {@code null} if asynchronous provider is unable to provide the local address
+   * @return The local address that the client initiated the request from. May be {@code null} if asynchronous provider is unable to provide the local address
    */
   SocketAddress getLocalAddress();
 

Diff for: client/src/main/java/org/asynchttpclient/SslEngineFactory.java

@@ -19,7 +19,7 @@
 public interface SslEngineFactory {
 
   /**
-   * Creates new {@link SSLEngine}.
+   * Creates a new {@link SSLEngine}.
    *
    * @param config   the client config
    * @param peerHost the peer hostname