Update the Javadoc of ChannelHandler and ChannelHandlerContext

Motivation:

It's out of date and it has broken links, etc.

Modifications:

Backport the fixes from master (132af3a485015ff912bd567a47881814d2ce1828)

Result:

Better Javadoc

transport/src/main/java/io/netty/channel/ChannelHandler.java

@@ -26,25 +26,28 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Handles or intercepts a {@link ChannelInboundInvoker} or {@link ChannelOutboundInvoker} operation, and forwards it
+ * Handles an I/O event or intercepts an I/O operation, and forwards it to its next handler in
- * to the next handler in a {@link ChannelPipeline}.
+ * its {@link ChannelPipeline}.
  *
  * <h3>Sub-types</h3>
  * <p>
- * {@link ChannelHandler} itself does not provide many methods.  To handle a
+ * {@link ChannelHandler} itself does not provide many methods, but you usually have to implement one of its subtypes:
- * a {@link ChannelInboundInvoker} or {@link ChannelOutboundInvoker} operation
- * you need to implement its sub-interfaces.  There are many different sub-interfaces
- * which handles inbound and outbound operations.
- *
- * But the most useful for developers may be:
  * <ul>
- * <li>{@link ChannelInboundHandlerAdapter} handles and intercepts inbound operations</li>
+ * <li>{@link ChannelInboundHandler} to handle inbound I/O events, and</li>
- * <li>{@link ChannelOutboundHandlerAdapter} handles and intercepts outbound operations</li>
+ * <li>{@link ChannelOutboundHandler} to handle outbound I/O operations.</li>
  * </ul>
- *
+ * </p>
- * You will also find more detailed explanation from the documentation of
+ * <p>
- * each sub-interface on how an event is interpreted when it goes upstream and
+ * Alternatively, the following adapter classes are provided for your convenience:
- * downstream respectively.
+ * <ul>
+ * <li>{@link ChannelInboundHandlerAdapter} to handle inbound I/O events,</li>
+ * <li>{@link ChannelOutboundHandlerAdapter} to handle outbound I/O operations, and</li>
+ * <li>{@link ChannelDuplexHandler} to handle both inbound and outbound events</li>
+ * </ul>
+ * </p>
+ * <p>
+ * For more information, please refer to the documentation of each subtype.
+ * </p>
  *
  * <h3>The context object</h3>
  * <p>

transport/src/main/java/io/netty/channel/ChannelHandlerContext.java

@@ -35,8 +35,7 @@ import java.nio.channels.Channels;
  *
  * <h3>Notify</h3>
  *
- * You can notify the closest handler in the
+ * You can notify the closest handler in the same {@link ChannelPipeline} by calling one of the various method.
- * same {@link ChannelPipeline} by calling one of the various methods provided here.
  * Please refer to {@link ChannelPipeline} to understand how an event flows.
  *
  * <h3>Modifying a pipeline</h3>
@@ -127,8 +126,7 @@ import java.nio.channels.Channels;
  * what fundamental differences they have, how they flow in a  pipeline,  and how to handle
  * the operation in your application.
  */
-public interface ChannelHandlerContext
+public interface ChannelHandlerContext extends AttributeMap {
-         extends AttributeMap {
 
     /**
      * Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}.
@@ -136,9 +134,7 @@ public interface ChannelHandlerContext
     Channel channel();
 
     /**
-     * The {@link EventExecutor} that is used to dispatch the events. This can also be used to directly
+     * Returns the {@link EventExecutor} which is used to execute an arbitrary task.
-     * submit tasks that get executed in the event loop. For more information please refer to the
-     * {@link EventExecutor} javadoc.
      */
     EventExecutor executor();