Add and correct javadocs

codec/src/main/java/io/netty/handler/codec/ByteToMessageCodec.java

@@ -58,11 +58,20 @@ public abstract class ByteToMessageCodec<I> extends ChannelDuplexHandler {
         }
     };
 
+    /**
+     * Create a new instance which will try to detect the types to encode out of the type parameter
+     * of the class.
+     */
     protected ByteToMessageCodec() {
         checkForSharableAnnotation();
         outboundMsgMatcher = TypeParameterMatcher.find(this, ByteToMessageCodec.class, "I");
     }
 
+    /**
+     * Create a new instance.
+     *
+     * @param outboundMessageType   The type of messages to encode
+     */
     protected ByteToMessageCodec(Class<? extends I> outboundMessageType) {
         checkForSharableAnnotation();
         outboundMsgMatcher = TypeParameterMatcher.get(outboundMessageType);
@@ -74,6 +83,11 @@ public abstract class ByteToMessageCodec<I> extends ChannelDuplexHandler {
         }
     }
 
+    /**
+     * Returns {@code true} if and only if the specified message can be encoded by this codec.
+     *
+     * @param msg the message
+     */
     public boolean acceptOutboundMessage(Object msg) throws Exception {
         return outboundMsgMatcher.match(msg);
     }

codec/src/main/java/io/netty/handler/codec/LengthFieldPrepender.java

@@ -129,7 +129,6 @@ public class LengthFieldPrepender extends MessageToByteEncoder<ByteBuf> {
 
     @Override
     protected void encode(ChannelHandlerContext ctx, ByteBuf msg, ByteBuf out) throws Exception {
-
         int length = msg.readableBytes() + lengthAdjustment;
         if (lengthIncludesLengthFieldLength) {
             length += lengthFieldLength;

codec/src/main/java/io/netty/handler/codec/MessageToByteEncoder.java

@@ -18,7 +18,9 @@ package io.netty.handler.codec;
 import io.netty.buffer.ByteBuf;
 import io.netty.buffer.Unpooled;
 import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.ChannelOutboundHandler;
 import io.netty.channel.ChannelOutboundHandlerAdapter;
+import io.netty.channel.ChannelPipeline;
 import io.netty.channel.ChannelPromise;
 import io.netty.util.ReferenceCountUtil;
 import io.netty.util.internal.TypeParameterMatcher;
@@ -46,24 +48,49 @@ public abstract class MessageToByteEncoder<I> extends ChannelOutboundHandlerAdap
     private final TypeParameterMatcher matcher;
     private final boolean preferDirect;
 
+    /**
+     * @see {@link #MessageToByteEncoder(boolean)} with {@code true} as boolean parameter.
+     */
     protected MessageToByteEncoder() {
         this(true);
     }
 
+    /**
+     * @see {@link #MessageToByteEncoder(Class, boolean)} with {@code true} as boolean value.
+     */
     protected MessageToByteEncoder(Class<? extends I> outboundMessageType) {
         this(outboundMessageType, true);
     }
 
+    /**
+     * Create a new instance which will try to detect the types to match out of the type parameter of the class.
+     *
+     * @param preferDirect          {@code true} if a direct {@link ByteBuf} should be tried to be used as target for
+     *                              the encoded messages. If {@code false} is used it will allocate a heap
+     *                              {@link ByteBuf}, which is backed by an byte array.
+     */
     protected MessageToByteEncoder(boolean preferDirect) {
         matcher = TypeParameterMatcher.find(this, MessageToByteEncoder.class, "I");
         this.preferDirect = preferDirect;
     }
 
+    /**
+     * Create a new instance
+     *
+     * @param outboundMessageType   The tpye of messages to match
+     * @param preferDirect          {@code true} if a direct {@link ByteBuf} should be tried to be used as target for
+     *                              the encoded messages. If {@code false} is used it will allocate a heap
+     *                              {@link ByteBuf}, which is backed by an byte array.
+     */
     protected MessageToByteEncoder(Class<? extends I> outboundMessageType, boolean preferDirect) {
         matcher = TypeParameterMatcher.get(outboundMessageType);
         this.preferDirect = preferDirect;
     }
 
+    /**
+     * Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
+     * {@link ChannelOutboundHandler} in the {@link ChannelPipeline}.
+     */
     public boolean acceptOutboundMessage(Object msg) throws Exception {
         return matcher.match(msg);
     }

codec/src/main/java/io/netty/handler/codec/MessageToMessageCodec.java

@@ -33,17 +33,17 @@ import java.util.List;
  *
  * <pre>
  *     public class NumberCodec extends
- *             {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}, {@link Long}, {@link Integer}&gt; {
+ *             {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}&gt; {
  *         {@code @Override}
- *         public {@link Long} decode({@link ChannelHandlerContext} ctx, {@link Integer} msg)
+ *         public {@link Long} decode({@link ChannelHandlerContext} ctx, {@link Integer} msg, List&lt;Object&gt; out)
  *                 throws {@link Exception} {
- *             return msg.longValue();
+ *             out.add(msg.longValue());
  *         }
  *
  *         {@code @Overrride}
- *         public {@link Integer} encode({@link ChannelHandlerContext} ctx, {@link Long} msg)
+ *         public {@link Integer} encode({@link ChannelHandlerContext} ctx, {@link Long} msg, List&lt;Object&gt; out)
  *                 throws {@link Exception} {
- *             return msg.intValue();
+ *             out.add(msg.intValue());
  *         }
  *     }
  * </pre>
@@ -85,11 +85,21 @@ public abstract class MessageToMessageCodec<INBOUND_IN, OUTBOUND_IN> extends Cha
     private final TypeParameterMatcher inboundMsgMatcher;
     private final TypeParameterMatcher outboundMsgMatcher;
 
+    /**
+     * Create a new instance which will try to detect the types to decode and encode out of the type parameter
+     * of the class.
+     */
     protected MessageToMessageCodec() {
         inboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "INBOUND_IN");
         outboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "OUTBOUND_IN");
     }
 
+    /**
+     * Create a new instance.
+     *
+     * @param inboundMessageType    The type of messages to decode
+     * @param outboundMessageType   The type of messages to encode
+     */
     protected MessageToMessageCodec(
             Class<? extends INBOUND_IN> inboundMessageType, Class<? extends OUTBOUND_IN> outboundMessageType) {
         inboundMsgMatcher = TypeParameterMatcher.get(inboundMessageType);

codec/src/main/java/io/netty/handler/codec/MessageToMessageDecoder.java

@@ -16,7 +16,9 @@
 package io.netty.handler.codec;
 
 import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.ChannelInboundHandler;
 import io.netty.channel.ChannelInboundHandlerAdapter;
+import io.netty.channel.ChannelPipeline;
 import io.netty.util.ReferenceCountUtil;
 import io.netty.util.ReferenceCounted;
 import io.netty.util.internal.RecyclableArrayList;
@@ -52,14 +54,26 @@ public abstract class MessageToMessageDecoder<I> extends ChannelInboundHandlerAd
 
     private final TypeParameterMatcher matcher;
 
+    /**
+     * Create a new instance which will try to detect the types to match out of the type parameter of the class.
+     */
     protected MessageToMessageDecoder() {
         matcher = TypeParameterMatcher.find(this, MessageToMessageDecoder.class, "I");
     }
 
+    /**
+     * Create a new instance
+     *
+     * @param inboundMessageType    The type of messages to match and so decode
+     */
     protected MessageToMessageDecoder(Class<? extends I> inboundMessageType) {
         matcher = TypeParameterMatcher.get(inboundMessageType);
     }
 
+    /**
+     * Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
+     * {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
+     */
     public boolean acceptInboundMessage(Object msg) throws Exception {
         return matcher.match(msg);
     }

codec/src/main/java/io/netty/handler/codec/MessageToMessageEncoder.java

@@ -16,7 +16,9 @@
 package io.netty.handler.codec;
 
 import io.netty.channel.ChannelHandlerContext;
+import io.netty.channel.ChannelOutboundHandler;
 import io.netty.channel.ChannelOutboundHandlerAdapter;
+import io.netty.channel.ChannelPipeline;
 import io.netty.channel.ChannelPromise;
 import io.netty.util.ReferenceCountUtil;
 import io.netty.util.ReferenceCounted;
@@ -51,14 +53,26 @@ public abstract class MessageToMessageEncoder<I> extends ChannelOutboundHandlerA
 
     private final TypeParameterMatcher matcher;
 
+    /**
+     * Create a new instance which will try to detect the types to match out of the type parameter of the class.
+     */
     protected MessageToMessageEncoder() {
         matcher = TypeParameterMatcher.find(this, MessageToMessageEncoder.class, "I");
     }
 
+    /**
+     * Create a new instance
+     *
+     * @param outboundMessageType   The type of messages to match and so encode
+     */
     protected MessageToMessageEncoder(Class<? extends I> outboundMessageType) {
         matcher = TypeParameterMatcher.get(outboundMessageType);
     }
 
+    /**
+     * Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
+     * {@link ChannelOutboundHandler} in the {@link ChannelPipeline}.
+     */
     public boolean acceptOutboundMessage(Object msg) throws Exception {
         return matcher.match(msg);
     }

codec/src/main/java/io/netty/handler/codec/ReplayingDecoder.java

@@ -36,14 +36,14 @@ import java.util.List;
  * availability of the required bytes.  For example, the following
  * {@link ByteToMessageDecoder} implementation:
  * <pre>
- * public class IntegerHeaderFrameDecoder extends {@link ByteToMessageDecoder}&lt;{@link ByteBuf}&gt; {
+ * public class IntegerHeaderFrameDecoder extends {@link ByteToMessageDecoder} {
  *
  *   {@code @Override}
- *   protected ByteBuf decode({@link ChannelHandlerContext} ctx,
+ *   protected void decode({@link ChannelHandlerContext} ctx,
- *                           {@link ByteBuf} in) throws Exception {
+ *                           {@link ByteBuf} in, List&lt;Object&gt; out) throws Exception {
  *
  *     if (in.readableBytes() &lt; 4) {
- *        return <strong>null</strong>;
+ *        return;
  *     }
  *
  *     in.markReaderIndex();
@@ -51,22 +51,22 @@ import java.util.List;
  *
  *     if (in.readableBytes() &lt; length) {
  *        in.resetReaderIndex();
- *        return <strong>null</strong>;
+ *        return;
  *     }
  *
- *     return in.readBytes(length);
+ *     out.add(in.readBytes(length));
  *   }
  * }
  * </pre>
  * is simplified like the following with {@link ReplayingDecoder}:
  * <pre>
  * public class IntegerHeaderFrameDecoder
- *      extends {@link ReplayingDecoder}&lt;{@link ByteBuf},{@link Void}&gt; {
+ *      extends {@link ReplayingDecoder}&lt;{@link Void}&gt; {
  *
- *   protected Object decode({@link ChannelHandlerContext} ctx,
+ *   protected void decode({@link ChannelHandlerContext} ctx,
  *                           {@link ByteBuf} buf) throws Exception {
  *
- *     return buf.readBytes(buf.readInt());
+ *     out.add(buf.readBytes(buf.readInt()));
  *   }
  * }
  * </pre>

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

@@ -35,30 +35,55 @@ import io.netty.util.internal.TypeParameterMatcher;
  *     }
  * </pre>
  *
+ * Be aware that depending of the constructor parameters it will release all handled messages.
+ *
  */
 public abstract class SimpleChannelInboundHandler<I> extends ChannelInboundHandlerAdapter {
 
     private final TypeParameterMatcher matcher;
     private final boolean autoRelease;
 
+    /**
+     * @see {@link #SimpleChannelInboundHandler(boolean)} with {@code true} as boolean parameter.
+     */
     protected SimpleChannelInboundHandler() {
         this(true);
     }
 
+    /**
+     * Create a new instance which will try to detect the types to match out of the type parameter of the class.
+     *
+     * @param autoRelease   {@code true} if handled messages should be released automatically by pass them to
+     *                      {@link ReferenceCountUtil#release(Object)}.
+     */
     protected SimpleChannelInboundHandler(boolean autoRelease) {
         matcher = TypeParameterMatcher.find(this, SimpleChannelInboundHandler.class, "I");
         this.autoRelease = autoRelease;
     }
 
+    /**
+     * @see {@link #SimpleChannelInboundHandler(Class, boolean)} with {@code true} as boolean value.
+     */
     protected SimpleChannelInboundHandler(Class<? extends I> inboundMessageType) {
         this(inboundMessageType, true);
     }
 
+    /**
+     * Create a new instance
+     *
+     * @param inboundMessageType    The type of messages to match
+     * @param autoRelease           {@code true} if handled messages should be released automatically by pass them to
+     *                              {@link ReferenceCountUtil#release(Object)}.
+     */
     protected SimpleChannelInboundHandler(Class<? extends I> inboundMessageType, boolean autoRelease) {
         matcher = TypeParameterMatcher.get(inboundMessageType);
         this.autoRelease = autoRelease;
     }
 
+    /**
+     * Returns {@code true} if the given message should be handled. If {@code false} it will be passed to the next
+     * {@link ChannelInboundHandler} in the {@link ChannelPipeline}.
+     */
     public boolean acceptInboundMessage(Object msg) throws Exception {
         return matcher.match(msg);
     }

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

@@ -15,6 +15,7 @@
  */
 package io.netty.channel;
 
+import io.netty.util.concurrent.EventExecutorGroup;
 import io.netty.util.concurrent.SingleThreadEventExecutor;
 
 import java.util.concurrent.ThreadFactory;
@@ -25,6 +26,9 @@ import java.util.concurrent.ThreadFactory;
  */
 public abstract class SingleThreadEventLoop extends SingleThreadEventExecutor implements EventLoop {
 
+    /**
+     * @see {@link SingleThreadEventExecutor#SingleThreadEventExecutor(EventExecutorGroup, ThreadFactory, boolean)}
+     */
     protected SingleThreadEventLoop(EventLoopGroup parent, ThreadFactory threadFactory, boolean addTaskWakesUp) {
         super(parent, threadFactory, addTaskWakesUp);
     }