diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java
index d3a761b5ae..bd17a37cda 100644
--- a/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelInboundHandlerAdapter.java
@@ -18,6 +18,12 @@ package io.netty.channel;
 
 import io.netty.buffer.Buf;
 
+/**
+ * Abstract base class for a {@link ChannelHandler} that handles inbound data.
+ *
+ * Most of the times you either want to extend {@link ChannelInboundByteHandlerAdapter} or
+ * {@link ChannelInboundMessageHandlerAdapter}.
+ */
 public abstract class ChannelInboundHandlerAdapter
         extends ChannelStateHandlerAdapter implements ChannelInboundHandler {
 
@@ -25,10 +31,4 @@ public abstract class ChannelInboundHandlerAdapter
     public void freeInboundBuffer(ChannelHandlerContext ctx, Buf buf) throws Exception {
         buf.free();
     }
-
-    /**
-     * Does nothing by default. Sub-classes may override this if needed.
-     */
-    @Override
-    public abstract void inboundBufferUpdated(ChannelHandlerContext ctx) throws Exception;
 }
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandler.java b/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandler.java
index 14a0522cce..a24fdf280f 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandler.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandler.java
@@ -17,6 +17,9 @@ package io.netty.channel;
 
 import io.netty.buffer.ByteBuf;
 
+/**
+ * {@link ChannelOutboundHandler} which operates on bytes which are hold in a {@link ByteBuf}.
+ */
 public interface ChannelOutboundByteHandler extends ChannelOutboundHandler {
     @Override
     ByteBuf newOutboundBuffer(ChannelHandlerContext ctx) throws Exception;
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandlerAdapter.java
index 61307ddafe..73ed0da400 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundByteHandlerAdapter.java
@@ -17,6 +17,10 @@ package io.netty.channel;
 
 import io.netty.buffer.ByteBuf;
 
+/**
+ * Abstract base class which handles outgoing bytes
+ *
+ */
 public abstract class ChannelOutboundByteHandlerAdapter
         extends ChannelOutboundHandlerAdapter implements ChannelOutboundByteHandler {
     @Override
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
index 44d6f24fc0..2ed6d23646 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
@@ -17,13 +17,17 @@ package io.netty.channel;
 
 import io.netty.buffer.Buf;
 
+
+/**
+ * Abstract base class for a {@link ChannelHandler} that handles outbound data.
+ *
+ * Most of the times you either want to extend {@link ChannelOutboundByteHandlerAdapter} or
+ * {@link ChannelOutboundMessageHandlerAdapter}.
+ */
 public abstract class ChannelOutboundHandlerAdapter
         extends ChannelOperationHandlerAdapter implements ChannelOutboundHandler {
     @Override
     public void freeOutboundBuffer(ChannelHandlerContext ctx, Buf buf) throws Exception {
         buf.free();
     }
-
-    @Override
-    public abstract void flush(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
 }
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandler.java b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandler.java
index 9b337be3dc..8e81991dad 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandler.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandler.java
@@ -17,6 +17,12 @@ package io.netty.channel;
 
 import io.netty.buffer.MessageBuf;
 
+/**
+ * ChannelOutboundHandler implementation which operates on messages of a specific type
+ * by pass them in a {@link MessageBuf} and consume then from there.
+ *
+ * @param <I>   the message type
+ */
 public interface ChannelOutboundMessageHandler<I> extends ChannelOutboundHandler {
     @Override
     MessageBuf<I> newOutboundBuffer(ChannelHandlerContext ctx) throws Exception;
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
index ddd799ecd1..fb8af835f0 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundMessageHandlerAdapter.java
@@ -18,8 +18,14 @@ package io.netty.channel;
 import io.netty.buffer.MessageBuf;
 import io.netty.buffer.Unpooled;
 
+/**
+ * Abstract base class which handles messages of a specific type.
+ *
+ * @param <I>   The type of the messages to handle
+ */
 public abstract class ChannelOutboundMessageHandlerAdapter<I>
         extends ChannelOutboundHandlerAdapter implements ChannelOutboundMessageHandler<I> {
+
     @Override
     public MessageBuf<I> newOutboundBuffer(ChannelHandlerContext ctx) throws Exception {
         return Unpooled.messageBuffer();
diff --git a/transport/src/main/java/io/netty/channel/ChannelStateHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelStateHandlerAdapter.java
index f9d79df0bc..a79c06c280 100644
--- a/transport/src/main/java/io/netty/channel/ChannelStateHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelStateHandlerAdapter.java
@@ -16,11 +16,22 @@
 package io.netty.channel;
 
 
+/**
+ * Abstract base class for {@link ChannelStateHandler} implementations which provide
+ * implementations of all of their methods.
+ *
+ * This implementation just forward the operation to the next {@link ChannelHandler} in the
+ * {@link ChannelPipeline}. Sub-classes may override a method implementation to change this.
+ */
 public class ChannelStateHandlerAdapter implements ChannelStateHandler {
 
     // Not using volatile because it's used only for a sanity check.
     boolean added;
 
+    /**
+     * Return {@code true} if the implementation is {@link Sharable} and so can be added
+     * to different {@link ChannelPipeline}s.
+     */
     final boolean isSharable() {
         return getClass().isAnnotationPresent(Sharable.class);
     }