diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
index f8149e7624..b6e640402c 100644
--- a/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelInboundMessageHandlerAdapter.java
@@ -28,9 +28,6 @@ import io.netty.util.internal.TypeParameterMatcher;
  * <pre>
  *     public class StringHandler extends
  *             {@link ChannelInboundMessageHandlerAdapter}&lt;{@link String}&gt; {
- *         public StringToIntegerDecoder() {
- *             super(String.class);
- *         }
  *
  *         {@code @Override}
  *         public void messageReceived({@link ChannelHandlerContext} ctx, {@link String} message)
@@ -46,6 +43,32 @@ import io.netty.util.internal.TypeParameterMatcher;
  * and you want to add a {@link ByteBuf} to the next buffer in the {@link ChannelPipeline} use
  * {@link ChannelHandlerUtil#addToNextInboundBuffer(ChannelHandlerContext, Object)}.
  *
+ * <p>
+ * One limitation to keep in mind is that it is not possible to detect the handled message type of you specify
+ * {@code I} while instance your class. Because of this Netty does not allow to do so and will throw an Exception
+ * if you try. For this cases you should handle the type detection by your self by override the
+ * {@link #acceptInboundMessage(Object)} method and use {@link Object} as type parameter.
+ *
+ * <pre>
+ *    public class GenericHandler&lt;I&gt; extends
+ *             {@link ChannelInboundMessageHandlerAdapter}&lt;{@link Object}&gt; {
+ *
+ *         {@code @Override}
+ *         public void messageReceived({@link ChannelHandlerContext} ctx, {@link Object} message)
+ *                 throws {@link Exception} {
+ *             I msg = (I) message;
+ *             // Do something with the msg
+ *             ...
+ *             ...
+ *         }
+ *
+ *         {@code @Override}
+ *         public boolean acceptInboundMessage(Object msg) throws Exception {
+ *             // Add your check here
+ *         }
+ *     }
+ * </pre>
+ *
  * @param <I>   The type of the messages to handle
  */
 public abstract class ChannelInboundMessageHandlerAdapter<I>
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
index e913134d17..02bf38aeed 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
@@ -29,6 +29,31 @@ import io.netty.util.internal.TypeParameterMatcher;
  * and you want to add a {@link ByteBuf} to the next buffer in the {@link ChannelPipeline} use
  * {@link ChannelHandlerUtil#addToNextOutboundBuffer(ChannelHandlerContext, Object)}.
  *
+ * <p>
+ * One limitation to keep in mind is that it is not possible to detect the handled message type of you specify
+ * {@code I} while instance your class. Because of this Netty does not allow to do so and will throw an Exception
+ * if you try. For this cases you should handle the type detection by your self by override the
+ * {@link #acceptOutboundMessage(Object)} method and use {@link Object} as type parameter.
+ *
+ * <pre>
+ *    public class GenericHandler&lt;I&gt; extends
+ *             {@link ChannelOutboundMessageHandlerAdapter}&lt;{@link Object}&gt; {
+ *
+ *         {@code @Override}
+ *         public void flush({@link ChannelHandlerContext} ctx, {@link Object} message)
+ *                 throws {@link Exception} {
+ *             I msg = (I) message;
+ *             // Do something with the msg
+ *             ...
+ *             ...
+ *         }
+ *
+ *         {@code @Override}
+ *         public boolean acceptOutboundMessage(Object msg) throws Exception {
+ *             // Add your check here
+ *         }
+ *     }
+ * </pre>
  * @param <I>   The type of the messages to handle
  */
 public abstract class ChannelOutboundMessageHandlerAdapter<I>