Add more javadocs and replace some abstract methods with noops as we often implemented them as noops

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

@@ -195,6 +195,9 @@ public abstract class AbstractChannel extends DefaultAttributeMap implements Cha
         return remoteAddress;
     }
 
+    /**
+     * Reset the stored remoteAddress
+     */
     protected void invalidateRemoteAddress() {
         remoteAddress = null;
     }
@@ -330,7 +333,10 @@ public abstract class AbstractChannel extends DefaultAttributeMap implements Cha
         return pipeline.sendFile(region, future);
     }
 
-    protected abstract Unsafe newUnsafe();
+    /**
+     * Create a new {@link AbstractUnsafe} instance which will be used for the life-time of the {@link Channel}
+     */
+    protected abstract AbstractUnsafe newUnsafe();
 
     /**
      * Returns the ID of this channel.
@@ -393,6 +399,9 @@ public abstract class AbstractChannel extends DefaultAttributeMap implements Cha
         return strVal;
     }
 
+    /**
+     * {@link Unsafe} implementation which sub-classes must extend and use.
+     */
     protected abstract class AbstractUnsafe implements Unsafe {
 
         private final class FlushTask {
@@ -865,27 +874,86 @@ public abstract class AbstractChannel extends DefaultAttributeMap implements Cha
         }
     }
 
+    /**
+     * Return {@code true} if the given {@link EventLoop} is compatible with this instance.
+     */
     protected abstract boolean isCompatible(EventLoop loop);
 
+    /**
+     * Returns the {@link SocketAddress} which is bound locally.
+     */
     protected abstract SocketAddress localAddress0();
+
+    /**
+     * Return the {@link SocketAddress} which the {@link Channel} is connected to.
+     */
     protected abstract SocketAddress remoteAddress0();
 
-    protected abstract Runnable doRegister() throws Exception;
+    /**
+     * Is called after the {@link Channel} is registered with its {@link EventLoop} as part of the register process.
+     * You can return a {@link Runnable} which will be run as post-task of the registration process.
+     *
+     * Sub-classes may override this method as it will just return {@code null}
+     */
+    protected Runnable doRegister() throws Exception {
+        return null;
+    }
+
+    /**
+     * Bind the {@link Channel} to the {@link SocketAddress}
+     */
     protected abstract void doBind(SocketAddress localAddress) throws Exception;
+
+    /**
+     * Disconnect this {@link Channel} from its remote peer
+     */
     protected abstract void doDisconnect() throws Exception;
+
+    /**
+     * Will be called before the actual close operation will be performed. Sub-classes may override this as the default
+     * is to do nothing.
+     */
     protected void doPreClose() throws Exception {
         // NOOP by default
     }
 
+    /**
+     * Close the {@link Channel}
+     */
     protected abstract void doClose() throws Exception;
-    protected abstract void doDeregister() throws Exception;
+
+    /**
+     * Deregister the {@link Channel} from its {@link EventLoop}.
+     *
+     * Sub-classes may override this method
+     */
+    protected void doDeregister() throws Exception {
+        // NOOP
+    }
+
+    /**
+     * Flush the content of the given {@link ByteBuf} to the remote peer.
+     *
+     * Sub-classes may override this as this implementation will just thrown an {@link UnsupportedOperationException}
+     */
     protected void doFlushByteBuffer(ByteBuf buf) throws Exception {
         throw new UnsupportedOperationException();
     }
+
+    /**
+     * Flush the content of the given {@link MessageBuf} to the remote peer.
+     *
+     * Sub-classes may override this as this implementation will just thrown an {@link UnsupportedOperationException}
+     */
     protected void doFlushMessageBuffer(MessageBuf<Object> buf) throws Exception {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Flush the content of the given {@link FileRegion} to the remote peer.
+     *
+     * Sub-classes may override this as this implementation will just thrown an {@link UnsupportedOperationException}
+     */
     protected void doFlushFileRegion(FileRegion region, ChannelFuture future) throws Exception {
         throw new UnsupportedOperationException();
     }
@@ -898,6 +966,9 @@ public abstract class AbstractChannel extends DefaultAttributeMap implements Cha
         }
     }
 
+    /**
+     * Return {@code true} if a flush to the {@link Channel} is currently pending.
+     */
     protected abstract boolean isFlushPending();
 
     private final class CloseFuture extends DefaultChannelFuture implements ChannelFuture.Unsafe {

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

@@ -74,16 +74,6 @@ public abstract class AbstractServerChannel extends AbstractChannel implements S
         throw new UnsupportedOperationException();
     }
 
-    @Override
-    protected void doFlushByteBuffer(ByteBuf buf) throws Exception {
-        throw new UnsupportedOperationException();
-    }
-
-    @Override
-    protected void doFlushMessageBuffer(MessageBuf<Object> buf) throws Exception {
-        throw new UnsupportedOperationException();
-    }
-
     @Override
     protected boolean isFlushPending() {
         return false;

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

@@ -118,7 +118,20 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
      */
     ChannelMetadata metadata();
 
+    /**
+     * Return the last {@link ByteBuf} of the {@link ChannelPipeline} which belongs to this {@link Channel}.
+     *
+     * This method may throw an {@link NoSuchBufferException} if you try to access this buffer and the
+     * {@link ChannelPipeline} does not contain any {@link ByteBuf}.
+     */
     ByteBuf outboundByteBuffer();
+
+    /**
+     * Return the last {@link MessageBuf} of the {@link ChannelPipeline} which belongs to this {@link Channel}.
+     *
+     * This method may throw an {@link NoSuchBufferException} if you try to access this buffer and the
+     * {@link ChannelPipeline} does not contain any {@link MessageBuf}.
+     */
     <T> MessageBuf<T> outboundMessageBuffer();
 
     /**

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

@@ -152,6 +152,11 @@ public interface ChannelHandlerContext
      * The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}.
      */
     ChannelHandler handler();
+
+    /**
+     * Return an unmodifiable {@link Set} that contains all the {@link ChannelHandlerType}s which are handled by this
+     * context and the {@link ChannelHandler} it belongs to.
+     */
     Set<ChannelHandlerType> types();
 
     /**

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

@@ -21,10 +21,25 @@ package io.netty.channel;
  */
 public interface ChannelStateHandler extends ChannelHandler {
 
+    /**
+     * The {@link Channel} of the {@link ChannelHandlerContext} was registered with its {@link EventLoop}
+     */
     void channelRegistered(ChannelHandlerContext ctx) throws Exception;
+
+    /**
+     * The {@link Channel} of the {@link ChannelHandlerContext} was unregistered from its {@link EventLoop}
+     */
     void channelUnregistered(ChannelHandlerContext ctx) throws Exception;
 
+    /**
+     * The {@link Channel} of the {@link ChannelHandlerContext} is now active
+     */
     void channelActive(ChannelHandlerContext ctx) throws Exception;
+
+    /**
+     * The {@link Channel} of the {@link ChannelHandlerContext} was registered is now inactive and reached its
+     * end of lifetime.
+     */
     void channelInactive(ChannelHandlerContext ctx) throws Exception;
 
     /**

transport/src/main/java/io/netty/channel/embedded/AbstractEmbeddedChannel.java

@@ -234,7 +234,7 @@ public abstract class AbstractEmbeddedChannel<O> extends AbstractChannel {
     }
 
     @Override
-    protected Unsafe newUnsafe() {
+    protected AbstractUnsafe newUnsafe() {
         return new DefaultUnsafe();
     }
 

transport/src/main/java/io/netty/channel/local/LocalChannel.java

@@ -108,7 +108,7 @@ public class LocalChannel extends AbstractChannel {
     }
 
     @Override
-    protected Unsafe newUnsafe() {
+    protected AbstractUnsafe newUnsafe() {
         return new LocalUnsafe();
     }
 

transport/src/main/java/io/netty/channel/local/LocalServerChannel.java

@@ -140,7 +140,7 @@ public class LocalServerChannel extends AbstractServerChannel {
     }
 
     @Override
-    protected Unsafe newUnsafe() {
+    protected AbstractUnsafe newUnsafe() {
         return new LocalServerUnsafe();
     }
 

transport/src/main/java/io/netty/channel/socket/aio/AbstractAioChannel.java

@@ -89,16 +89,6 @@ abstract class AbstractAioChannel extends AbstractChannel {
         return ch.isOpen();
     }
 
-    @Override
-    protected Runnable doRegister() throws Exception {
-        return null;
-    }
-
-    @Override
-    protected void doDeregister() throws Exception {
-        // NOOP
-    }
-
     @Override
     protected boolean isCompatible(EventLoop loop) {
         return loop instanceof AioEventLoop;

transport/src/main/java/io/netty/channel/socket/aio/AioChannelFinder.java

@@ -15,6 +15,9 @@
  */
 package io.netty.channel.socket.aio;
 
+/**
+ * Allow to fine the {@link AbstractAioChannel} for a task.
+ */
 interface AioChannelFinder {
 
     /**

transport/src/main/java/io/netty/channel/socket/aio/AioServerSocketChannel.java

@@ -34,7 +34,7 @@ import java.nio.channels.AsynchronousSocketChannel;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * {@link io.netty.channel.socket.ServerSocketChannel} implementation which uses NIO2.
+ * {@link ServerSocketChannel} implementation which uses NIO2.
  *
  * NIO2 is only supported on Java 7+.
  */
@@ -202,7 +202,7 @@ public class AioServerSocketChannel extends AbstractAioChannel implements Server
     }
 
     @Override
-    protected Unsafe newUnsafe() {
+    protected AbstractUnsafe newUnsafe() {
         return new AioServerSocketUnsafe();
     }
 

transport/src/main/java/io/netty/channel/socket/aio/AioSocketChannel.java

@@ -42,7 +42,7 @@ import java.util.concurrent.atomic.AtomicBoolean;
 
 
 /**
- * {@link io.netty.channel.socket.SocketChannel} implementation which uses NIO2.
+ * {@link SocketChannel} implementation which uses NIO2.
  *
  * NIO2 is only supported on Java 7+.
  */
@@ -544,7 +544,7 @@ public class AioSocketChannel extends AbstractAioChannel implements SocketChanne
     }
 
     @Override
-    protected Unsafe newUnsafe() {
+    protected AbstractUnsafe newUnsafe() {
         return new AioSocketChannelAsyncUnsafe();
     }
 

transport/src/main/java/io/netty/channel/socket/oio/AbstractOioChannel.java

@@ -105,17 +105,6 @@ abstract class AbstractOioChannel extends AbstractChannel {
         return loop instanceof OioEventLoop;
     }
 
-    @Override
-    protected Runnable doRegister() throws Exception {
-        // NOOP
-        return null;
-    }
-
-    @Override
-    protected void doDeregister() throws Exception {
-        // NOOP
-    }
-
     @Override
     protected boolean isFlushPending() {
         return false;