diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java b/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
index abc11403be..86818ddb4e 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundHandlerAdapter.java
@@ -93,6 +93,12 @@ public class ChannelOutboundHandlerAdapter extends ChannelHandlerAdapter impleme
         ctx.read();
     }
 
+    /**
+     * Calls {@link ChannelHandlerContext#write(MessageList, ChannelPromise)} to forward
+     * to the next {@link ChannelOutboundHandler} in the {@link ChannelPipeline}.
+     *
+     * Sub-classes may override this method to change behavior.
+     */
     @Override
     public void write(ChannelHandlerContext ctx, MessageList<Object> msgs, ChannelPromise promise) throws Exception {
         ctx.write(msgs, promise);
diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java b/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java
index 4f16f90aec..9549a23d94 100644
--- a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java
+++ b/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java
@@ -103,18 +103,11 @@ interface ChannelOutboundInvoker {
      * Request to write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
      * once the operation completes, either because the operation was successful or because of an error.
      *
-     * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}.
      * <p>
      * Be aware that the write could be only partially successful as the message may need to get encoded before write it
      * to the remote peer. In such cases the {@link ChannelFuture} will be failed with a
-     * {@link IncompleteFlushException}. In such cases you may want to call {@link #flush(ChannelPromise)} or
-     * {@link #flush()} to flush the rest of the data or just close the connection via {@link #close(ChannelPromise)}
-     * or {@link #close()} if it is not possible to recover.
+     * {@link IncompleteFlushException}.
      * <p>
-     * This will result in having the message added to the outbound buffer of the next {@link ChannelOutboundHandler}
-     * and the {@link ChannelOutboundHandler#flush(ChannelHandlerContext, ChannelPromise)}
-     * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
-     * {@link Channel}.
      */
     ChannelFuture write(Object msg);
     ChannelFuture write(MessageList<?> msgs);
@@ -208,7 +201,7 @@ interface ChannelOutboundInvoker {
 
     /**
      * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an
-     * {@link ChannelInboundHandler#inboundBufferUpdated(ChannelHandlerContext) inboundBufferUpdated} event if data was
+     * {@link ChannelInboundHandler#messageReceived(ChannelHandlerContext, MessageList)} event if data was
      * read, and triggers an
      * {@link ChannelInboundHandler#channelReadSuspended(ChannelHandlerContext) channelReadSuspended} event so the
      * handler can decide to continue reading.  If there's a pending read operation already, this method does nothing.
@@ -224,20 +217,10 @@ interface ChannelOutboundInvoker {
      * Request to write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
      * once the operation completes, either because the operation was successful or because of an error.
      *
-     * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}.
      * <p>
      * Be aware that the write could be only partially successful as the message may need to get encoded before write it
      * to the remote peer. In such cases the {@link ChannelFuture} will be failed with a
-     * {@link IncompleteFlushException}. In such cases you may want to call {@link #flush(ChannelPromise)} or
-     * {@link #flush()} to flush the rest of the data or just close the connection via {@link #close(ChannelPromise)}
-     * or {@link #close()} if it is not possible to recover.
-     *
-     * The given {@link ChannelPromise} will be notified.
-     * <p>
-     * This will result in having the message added to the outbound buffer of the next {@link ChannelOutboundHandler}
-     * and the {@link ChannelOutboundHandler#flush(ChannelHandlerContext, ChannelPromise)}
-     * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
-     * {@link Channel}.
+     * {@link IncompleteFlushException}.
      */
     ChannelFuture write(Object msg, ChannelPromise promise);
     ChannelFuture write(MessageList<?> msgs, ChannelPromise promise);
diff --git a/transport/src/main/java/io/netty/channel/MessageList.java b/transport/src/main/java/io/netty/channel/MessageList.java
index cba1c8c054..37b2b9ed1f 100644
--- a/transport/src/main/java/io/netty/channel/MessageList.java
+++ b/transport/src/main/java/io/netty/channel/MessageList.java
@@ -28,6 +28,12 @@ import java.util.ConcurrentModificationException;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 
+/**
+ * Datastructure which holds messages.
+ *
+ * You should call {@link #recycle()} once you are done with using it.
+ * @param <T>
+ */
 public final class MessageList<T> implements Iterable<T> {
 
     private static final int DEFAULT_INITIAL_CAPACITY = 8;