Comment clean up as advised

src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java

@@ -44,7 +44,7 @@ import org.jboss.netty.channel.ExceptionEvent;
 import org.jboss.netty.channel.SimpleChannelHandler;
 
 /**
- * A helper class which creates a new client-side {@link Channel} and make a
+ * A helper class which creates a new client-side {@link Channel} and makes a
  * connection attempt.
  *
  * <h3>Configuring a channel</h3>
@@ -83,7 +83,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  *
  * {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
  * is to specify a {@link ChannelPipelineFactory} by yourself and have full
- * control over how a new pipeline is created, at the cost of more complexity:
+ * control over how a new pipeline is created.  This approach is more complex:
  *
  * <pre>
  * ClientBootstrap b = ...;

src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java

@@ -117,7 +117,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  *
  * {@linkplain #setPipelineFactory(ChannelPipelineFactory) The second approach}
  * is to specify a {@link ChannelPipelineFactory} by yourself and have full
- * control over how a new pipeline is created, at the cost of more complexity:
+ * control over how a new pipeline is created.  This approach is more complex:
  *
  * <pre>
  * ServerBootstrap b = ...;

src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java

@@ -86,7 +86,7 @@ import java.net.SocketAddress;
  * <p>
  * You might want to refer to {@link ChannelUpstreamHandler} to see how a
  * {@link ChannelEvent} is interpreted when going upstream.  Also, please refer
- * to the {@link ChannelEvent} documentation to find out what a upstream event
+ * to the {@link ChannelEvent} documentation to find out what an upstream event
  * and a downstream event are and what fundamental differences they have, if
  * you didn't read yet.
  *

src/main/java/org/jboss/netty/channel/ChannelEvent.java

@@ -32,17 +32,17 @@ package org.jboss.netty.channel;
  *
  * <h3>Upstream events and downstream events, and their interpretation</h3>
  * <p>
- * Every event can be either a upstream event or a downstream event.
+ * Every event can be either an upstream event or a downstream event.
  * If an event flows from the first handler to the last handler in a
- * {@link ChannelPipeline}, we call it a upstream event and say <strong>"an
+ * {@link ChannelPipeline}, we call it an upstream event and say <strong>"an
  * event goes upstream."</strong>  If an event flows from the last handler to
  * the first handler in a {@link ChannelPipeline}, we call it a downstream
  * event and say <strong>"an event goes downstream."</strong>  (Please refer
  * to the diagram in {@link ChannelPipeline} for more explanation.)
  * <p>
  * A {@link ChannelEvent} is interpreted differently by a {@link ChannelHandler}
- * depending on whether the event is a upstream event or a downstream event.
+ * depending on whether the event is an upstream event or a downstream event.
- * A upstream event represents the notification of what happened in the past.
+ * An upstream event represents the notification of what happened in the past.
  * By contrast, a downstream event represents the request of what should happen
  * in the future.  For example, a {@link MessageEvent} represents the
  * notification of a received message when it goes upstream, while it
@@ -73,7 +73,7 @@ public interface ChannelEvent {
 
     /**
      * Returns the {@link ChannelFuture} which is associated with this event.
-     * If this event is a upstream event, this method will always return a
+     * If this event is an upstream event, this method will always return a
      * {@link SucceededChannelFuture} because the event has occurred already.
      * If this event is a downstream event (i.e. I/O request), the returned
      * future will be notified when the I/O request succeeds or fails.

src/main/java/org/jboss/netty/channel/ChannelHandler.java

@@ -29,16 +29,15 @@ package org.jboss.netty.channel;
  *
  * <h3>Sub-types</h3>
  * <p>
- * This is a tag interface.  There are two sub-interfaces which processes
+ * This is a tag interface.  There are two sub-interfaces which process a
- * a received event actually, one for upstream events and the other for
+ * received event, one for upstream events and the other for downstream events:
- * downstream events:
  * <ul>
- * <li>{@link ChannelUpstreamHandler} handles and intercepts a upstream {@link ChannelEvent}.</li>
+ * <li>{@link ChannelUpstreamHandler} handles and intercepts an upstream {@link ChannelEvent}.</li>
  * <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
  * </ul>
  *
  * You will also find more detailed explanation from the documentation of
- * each sub-type about how an event is interpreted when it goes upstream and
+ * each sub-type on how an event is interpreted when it goes upstream and
  * downstream respectively.
  *
  * <h3>The context object</h3>

src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java

@@ -26,7 +26,7 @@ package org.jboss.netty.channel;
  * Provides the properties and operations which are specific to the
  * {@link ChannelHandler} and the {@link ChannelPipeline} it belongs to.
  * Via a {@link ChannelHandlerContext}, a {@link ChannelHandler} can send
- * a upstream or downstream {@link ChannelEvent} to the next or previous
+ * an upstream or downstream {@link ChannelEvent} to the next or previous
  * {@link ChannelHandler} in the {@link ChannelPipeline}.
  *
  * <pre>

src/main/java/org/jboss/netty/channel/ChannelPipeline.java

@@ -55,7 +55,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
  * or {@link ChannelHandlerContext#sendDownstream(ChannelEvent)}.  The meaning
  * of the event is interpreted somewhat differently depending on whether it is
  * going upstream or going downstream. Please refer to {@link ChannelEvent} for
- * more explanation.
+ * more information.
  *
  * <pre>
  *
@@ -94,7 +94,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
  *  |             I/O Threads (Transport Implementation)               |
  *  +------------------------------------------------------------------+
  * </pre>
- * Please note that a upstream event flows from the first upstream handler
+ * Please note that an upstream event flows from the first upstream handler
  * to the last upstream handler (i.e. to the next) and a downstream event
  * flows from the last downstream handler to the first downstream handler
  * (i.e. to the previous).
@@ -130,7 +130,7 @@ import org.jboss.netty.handler.ssl.SslHandler;
  * <p>
  * A {@link ChannelHandler} can be added or removed at any time because a
  * {@link ChannelPipeline} is thread safe.  For example, you can insert a
- * {@link SslHandler} when a sensitive information is about to be exchanged,
+ * {@link SslHandler} when sensitive information is about to be exchanged,
  * and remove it after the exchange.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/ChannelStateEvent.java

@@ -26,9 +26,9 @@ package org.jboss.netty.channel;
 /**
  * A {@link ChannelEvent} which represents the change of the {@link Channel}
  * state.  It can mean the notification of a change or the request for a
- * change, depending on whether it is a upstream event or a downstream event
+ * change, depending on whether it is an upstream event or a downstream event
  * respectively.  Please refer to the {@link ChannelEvent} documentation to
- * find out what a upstream event and a downstream event are and what
+ * find out what an upstream event and a downstream event are and what
  * fundamental differences they have.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java

@@ -38,7 +38,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  *
  * <h3>Upstream events</h3>
  * <p>
- * A upstream event is an event which is supposed to be processed from the
+ * An upstream event is an event which is supposed to be processed from the
  * first handler to the last handler in the {@link ChannelPipeline}.
  * For example, all events initiated by an I/O thread are upstream events, and
  * they have the following meaning:
@@ -117,14 +117,14 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * <p>
  * You might want to refer to {@link ChannelDownstreamHandler} to see how a
  * {@link ChannelEvent} is interpreted when going downstream.  Also, please
- * refer to the {@link ChannelEvent} documentation to find out what a upstream
+ * refer to the {@link ChannelEvent} documentation to find out what an upstream
  * event and a downstream event are and what fundamental differences they have,
  * if you didn't read yet.
  *
  * <h3>{@link SimpleChannelHandler}</h3>
  * <p>
  * In most cases, you will get to use a {@link SimpleChannelHandler} to
- * implement a upstream handler because it provides an individual handler
+ * implement an upstream handler because it provides an individual handler
  * method for each event type.  You might want to implement this interface
  * directly though if you want to handle various types of events in more
  * generic way.

src/main/java/org/jboss/netty/channel/ChildChannelStateEvent.java

@@ -25,7 +25,7 @@ package org.jboss.netty.channel;
 /**
  * A {@link ChannelEvent} which represents the notification of the state of
  * a child {@link Channel}.  This event is for going upstream only.  Please
- * refer to the {@link ChannelEvent} documentation to find out what a upstream
+ * refer to the {@link ChannelEvent} documentation to find out what an upstream
  * event and a downstream event are and what fundamental differences they have.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/ExceptionEvent.java

@@ -26,7 +26,7 @@ package org.jboss.netty.channel;
  * A {@link ChannelEvent} which represents the notification of an exception
  * raised by a {@link ChannelHandler} or an I/O thread.  This event is for
  * going upstream only.  Please refer to the {@link ChannelEvent} documentation
- * to find out what a upstream event and a downstream event are and what
+ * to find out what an upstream event and a downstream event are and what
  * fundamental differences they have.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/MessageEvent.java

@@ -27,9 +27,9 @@ import java.net.SocketAddress;
 /**
  * A {@link ChannelEvent} which represents the transmission or reception of a
  * message.  It can mean the notification of a received message or the request
- * for writing a message, depending on whether it is a upstream event or a
+ * for writing a message, depending on whether it is an upstream event or a
  * downstream event respectively.  Please refer to the {@link ChannelEvent}
- * documentation to find out what a upstream event and a downstream event are
+ * documentation to find out what an upstream event and a downstream event are
  * and what fundamental differences they have.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)

src/main/java/org/jboss/netty/channel/socket/nio/NioClientSocketChannelFactory.java

@@ -62,7 +62,7 @@ import org.jboss.netty.channel.socket.SocketChannel;
  * <h3>Life cycle of threads and graceful shutdown</h3>
  * <p>
  * All threads are acquired from the {@link Executor}s which were specified
- * when a {@link NioClientSocketChannelFactory} is created.  A boss thread is
+ * when a {@link NioClientSocketChannelFactory} was created.  A boss thread is
  * acquired from the {@code bossExecutor}, and worker threads are acquired from
  * the {@code workerExecutor}.  Therefore, you should make sure the specified
  * {@link Executor}s are able to lend the sufficient number of threads.

src/main/java/org/jboss/netty/channel/socket/nio/NioServerSocketChannelFactory.java

@@ -64,7 +64,7 @@ import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
  * <h3>Life cycle of threads and graceful shutdown</h3>
  * <p>
  * All threads are acquired from the {@link Executor}s which were specified
- * when a {@link NioServerSocketChannelFactory} is created.  Boss threads are
+ * when a {@link NioServerSocketChannelFactory} was created.  Boss threads are
  * acquired from the {@code bossExecutor}, and worker threads are acquired from
  * the {@code workerExecutor}.  Therefore, you should make sure the specified
  * {@link Executor}s are able to lend the sufficient number of threads.

src/main/java/org/jboss/netty/channel/socket/nio/NioSocketChannelConfig.java

@@ -62,7 +62,7 @@ public interface NioSocketChannelConfig extends SocketChannelConfig {
     /**
      * Returns the maximum loop count for a write operation until
      * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
-     * It is similar to what a spin lock is for in concurrency programming.
+     * It is similar to what a spin lock is used for in concurrency programming.
      * It improves memory utilization and write throughput depending on
      * the platform that JVM runs on.  The default value is {@code 16}.
      */
@@ -71,7 +71,7 @@ public interface NioSocketChannelConfig extends SocketChannelConfig {
     /**
      * Sets the maximum loop count for a write operation until
      * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
-     * It is similar to what a spin lock is for in concurrency programming.
+     * It is similar to what a spin lock is used for in concurrency programming.
      * It improves memory utilization and write throughput depending on
      * the platform that JVM runs on.  The default value is {@code 16}.
      *

src/main/java/org/jboss/netty/channel/socket/oio/OioClientSocketChannelFactory.java

@@ -51,7 +51,7 @@ import org.jboss.netty.channel.socket.SocketChannel;
  * <h3>Life cycle of threads and graceful shutdown</h3>
  * <p>
  * Worker threads are acquired from the {@link Executor} which was specified
- * when a {@link OioClientSocketChannelFactory} is created (i.e. {@code workerExecutor}.)
+ * when a {@link OioClientSocketChannelFactory} was created (i.e. {@code workerExecutor}.)
  * Therefore, you should make sure the specified {@link Executor} is able to
  * lend the sufficient number of threads.
  * <p>

src/main/java/org/jboss/netty/channel/socket/oio/OioServerSocketChannelFactory.java

@@ -61,7 +61,7 @@ import org.jboss.netty.channel.socket.ServerSocketChannelFactory;
  * <h3>Life cycle of threads and graceful shutdown</h3>
  * <p>
  * All threads are acquired from the {@link Executor}s which were specified
- * when a {@link OioServerSocketChannelFactory} is created.  Boss threads are
+ * when a {@link OioServerSocketChannelFactory} was created.  Boss threads are
  * acquired from the {@code bossExecutor}, and worker threads are acquired from
  * the {@code workerExecutor}.  Therefore, you should make sure the specified
  * {@link Executor}s are able to lend the sufficient number of threads.

src/main/java/org/jboss/netty/handler/execution/ExecutionHandler.java

@@ -31,7 +31,7 @@ import org.jboss.netty.channel.ChannelPipelineCoverage;
 import org.jboss.netty.channel.ChannelUpstreamHandler;
 
 /**
- * Forwards a upstream {@link ChannelEvent} to an {@link Executor}.
+ * Forwards an upstream {@link ChannelEvent} to an {@link Executor}.
  * <p>
  * You can implement various thread model by adding this handler to a
  * {@link ChannelPipeline}.  The most common use case of this handler is to