From 95ff172c8265cb14f7d2bad264de0e4f2e9e4fae Mon Sep 17 00:00:00 2001
From: Norman Maurer <nmaurer@redhat.com>
Date: Tue, 4 Mar 2014 06:34:14 +0100
Subject: [PATCH] Corrected inconsistencies in the Javadoc.

Port of 80030493b9f7824c02dc88260c2579afc0aed8bc
---
 .../java/io/netty/channel/ChannelHandler.java | 21 +++++++------------
 .../netty/channel/ChannelHandlerContext.java  |  6 +++---
 .../channel/SimpleChannelInboundHandler.java  |  2 +-
 3 files changed, 12 insertions(+), 17 deletions(-)

diff --git a/transport/src/main/java/io/netty/channel/ChannelHandler.java b/transport/src/main/java/io/netty/channel/ChannelHandler.java
index fd6191e69f..4c3cd35b2b 100644
--- a/transport/src/main/java/io/netty/channel/ChannelHandler.java
+++ b/transport/src/main/java/io/netty/channel/ChannelHandler.java
@@ -53,7 +53,7 @@ import java.lang.annotation.Target;
  * {@link ChannelPipeline} it belongs to via a context object.  Using the
  * context object, the {@link ChannelHandler} can pass events upstream or
  * downstream, modify the pipeline dynamically, or store the information
- * (attachment) which is specific to the handler.
+ *  (using {@link AttributeKey}s) which is specific to the handler.
  *
  * <h3>State management</h3>
  *
@@ -69,7 +69,7 @@ import java.lang.annotation.Target;
  *     <b>private boolean loggedIn;</b>
  *
  *     {@code @Override}
- *     public void channelRead({@link ChannelHandlerContext} ctx, Message message) {
+ *     public void channelRead0({@link ChannelHandlerContext} ctx, Message message) {
  *         {@link Channel} ch = e.getChannel();
  *         if (message instanceof LoginMessage) {
  *             authenticate((LoginMessage) message);
@@ -101,11 +101,11 @@ import java.lang.annotation.Target;
  *
  * </pre>
  *
- * <h4>Using an attachment</h4>
+ * <h4>Using {@link AttributeKey}</h4>
  *
  * Although it's recommended to use member variables to store the state of a
  * handler, for some reason you might not want to create many handler instances.
- * In such a case, you can use an <em>attachment</em> which is provided by
+ * In such a case, you can use {@link AttributeKey}s which is provided by
  * {@link ChannelHandlerContext}:
  * <pre>
  * public interface Message {
@@ -114,17 +114,12 @@ import java.lang.annotation.Target;
  *
  * {@code @Sharable}
  * public class DataServerHandler extends {@link SimpleChannelInboundHandler}&lt;Message&gt; {
- *   private final {@link AttributeKey}&lt{@link Boolean}&gt auth =
+ *     private final {@link AttributeKey}&lt{@link Boolean}&gt auth =
  *           {@link AttributeKey#valueOf(String) AttributeKey.valueOf("auth")};
  *
- *   // This handler will receive a sequence of increasing integers starting
- *   // from 1.
- *   {@code @Override}
- *   public void channelRead({@link ChannelHandlerContext} ctx, {@link Integer} integer) {
- *     {@link Attribute}&lt{@link Boolean}&gt attr = ctx.attr(auth);
- *
  *     {@code @Override}
  *     public void channelRead({@link ChannelHandlerContext} ctx, Message message) {
+ *         {@link Attribute}&lt{@link Boolean}&gt attr = ctx.attr(auth);
  *         {@link Channel} ch = ctx.channel();
  *         if (message instanceof LoginMessage) {
  *             authenticate((LoginMessage) o);
@@ -140,7 +135,7 @@ import java.lang.annotation.Target;
  *     ...
  * }
  * </pre>
- * Now that the state of the handler is stored as an attachment, you can add the
+ * Now that the state of the handler isattached to the {@link ChannelHandlerContext}, you can add the
  * same handler instance to different pipelines:
  * <pre>
  * public class DataServerInitializer extends {@link ChannelInitializer}&lt{@link Channel}&gt {
@@ -157,7 +152,7 @@ import java.lang.annotation.Target;
  *
  * <h4>The {@code @Sharable} annotation</h4>
  * <p>
- * In the examples above which used an attachment,
+ * In the example above which used an {@link AttributeKey},
  * you might have noticed the {@code @Sharable} annotation.
  * <p>
  * If a {@link ChannelHandler} is annotated with the {@code @Sharable}
diff --git a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java
index 420f17b0e7..0fca9d71f0 100644
--- a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java
+++ b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java
@@ -43,7 +43,7 @@ import java.nio.channels.Channels;
  *
  * You can get the {@link ChannelPipeline} your handler belongs to by calling
  * {@link #pipeline()}.  A non-trivial application could insert, remove, or
- * replace handlers in the pipeline dynamically in runtime.
+ * replace handlers in the pipeline dynamically at runtime.
  *
  * <h3>Retrieving for later use</h3>
  *
@@ -81,7 +81,7 @@ import java.nio.channels.Channels;
  * {@link ChannelHandlerContext}s if it is added to one or more
  * {@link ChannelPipeline}s more than once.
  * <p>
- * For example, the following handler will have as many independent attachments
+ * For example, the following handler will have as many independent {@link AttributeKey}s
  * as how many times it is added to pipelines, regardless if it is added to the
  * same pipeline multiple times or added to different pipelines multiple times:
  * <pre>
@@ -107,7 +107,7 @@ import java.nio.channels.Channels;
  *
  * // Different context objects are given to "f1", "f2", "f3", and "f4" even if
  * // they refer to the same handler instance.  Because the FactorialHandler
- * // stores its state in a context object (as an attachment), the factorial is
+ * // stores its state in a context object (as an (using an {@link AttributeKey}), the factorial is
  * // calculated correctly 4 times once the two pipelines (p1 and p2) are active.
  * FactorialHandler fh = new FactorialHandler();
  *
diff --git a/transport/src/main/java/io/netty/channel/SimpleChannelInboundHandler.java b/transport/src/main/java/io/netty/channel/SimpleChannelInboundHandler.java
index 85c1303855..6cd2f682df 100644
--- a/transport/src/main/java/io/netty/channel/SimpleChannelInboundHandler.java
+++ b/transport/src/main/java/io/netty/channel/SimpleChannelInboundHandler.java
@@ -39,7 +39,7 @@ import io.netty.util.internal.TypeParameterMatcher;
  *
  * <h3>Forward compatibility notice</h3>
  * <p>
- * Please keep in mind that {@link #channelRead0(ChannelHandlerContext, Object)} will be renamed to
+ * Please keep in mind that {@link #channelRead0(ChannelHandlerContext, I)} will be renamed to
  * {@code messageReceived(ChannelHandlerContext, I)} in 5.0.
  * </p>
  */