Some javadocs love

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

@@ -26,6 +26,8 @@ import java.net.InetSocketAddress;
 import java.net.SocketAddress;
 import java.nio.channels.SelectionKey;
 
+import sun.awt.windows.ThemeReader;
+
 
 /**
  * A nexus to a network socket or a component which is capable of I/O
@@ -113,6 +115,9 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu
      */
     Integer id();
 
+    /**
+     * Return the {@link EventLoop} this {@link Channel} was registered too.
+     */
     EventLoop eventLoop();
 
     /**
@@ -138,6 +143,9 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu
     boolean isRegistered();
     boolean isActive();
 
+    /**
+     * Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}.
+     */
     ChannelMetadata metadata();
 
     ByteBuf outboundByteBuffer();
@@ -176,25 +184,99 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFu
      */
     ChannelFuture closeFuture();
 
+    /**
+     * <strong>Caution</strong> for transport implementations use only!
+     */
     Unsafe unsafe();
 
+    /**
+     * <strong>Unsafe</strong> operations that should <strong>never</strong> be called
+     * from user-code. These methods are only provided to implement the actual transport.
+     */
     interface Unsafe {
+        /**
+         * Return the {@link ChannelHandlerContext} which is directly connected to the outbound of the
+         * underlying transport.
+         */
         ChannelHandlerContext directOutboundContext();
+
+        /**
+         * Return a {@link VoidChannelFuture}. This method always return the same instance.
+         */
         ChannelFuture voidFuture();
 
+        /**
+         * Return the {@link SocketAddress} to which is bound local or
+         * <code>null</code> if none.
+         */
         SocketAddress localAddress();
+
+        /**
+         * Return the {@link SocketAddress} to which is bound remote or
+         * <code>null</code> if none is bound yet.
+         */
         SocketAddress remoteAddress();
 
+        /**
+         * Register the {@link Channel} of the {@link ChannelFuture} with the {@link EventLoop} and notify
+         * the {@link ChannelFuture} once the registration was complete.
+         */
         void register(EventLoop eventLoop, ChannelFuture future);
+
+        /**
+         * Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelFuture} and notify
+         * it once its done.
+         */
         void bind(SocketAddress localAddress, ChannelFuture future);
+
+        /**
+         * Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}.
+         * If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just
+         * pass <code>null</code> to it.
+         *
+         * The {@link ChannelFuture} will get notified once the connect operation was complete.
+         */
         void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
+
+        /**
+         * Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the
+         * operation was complete.
+         */
         void disconnect(ChannelFuture future);
+
+        /**
+         * Close the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the
+         * operation was complete.
+         */
         void close(ChannelFuture future);
+
+        /**
+         * Deregister the {@link Channel} of the {@link ChannelFuture} from {@link EventLoop} and notify the
+         * {@link ChannelFuture} once the operation was complete.
+         */
         void deregister(ChannelFuture future);
 
+        /**
+         * Flush out all data that was buffered in the buffer of the {@link #directOutboundContext()} and was not
+         * flushed out yet. After that is done the {@link ChannelFuture} will get notified
+         */
         void flush(ChannelFuture future);
+
+        /**
+         * Flush out all data now.
+         */
         void flushNow();
+
+        /**
+         * Suspend reads from the underlying transport, which basicly has the effect of no new data that will
+         * get dispatched.
+         */
         void suspendRead();
+
+        /**
+         * Resume reads from the underlying transport. If {@link #suspendRead()} was not called before, this
+         * has no effect.
+         */
         void resumeRead();
     }
 }

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

@@ -60,6 +60,9 @@ import java.util.Map;
  */
 public interface ChannelConfig {
 
+    /**
+     * Return all set {@link ChannelOption}'s.
+     */
     Map<ChannelOption<?>, Object> getOptions();
 
     /**
@@ -67,6 +70,9 @@ public interface ChannelConfig {
      */
     boolean setOptions(Map<ChannelOption<?>, ?> options);
 
+    /**
+     * Return the value of the given {@link ChannelOption}
+     */
     <T> T getOption(ChannelOption<T> option);
 
     /**

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

@@ -15,8 +15,28 @@
  */
 package io.netty.channel;
 
+/**
+ * Factory which is responsible to create new {@link ChannelFuture}'s
+ *
+ */
 public interface ChannelFutureFactory {
+
+    /**
+     * Create a new {@link ChannelFuture}
+     */
     ChannelFuture newFuture();
+
+    /**
+     * Create a new {@link ChannelFuture} which is marked as successes already. So {@link ChannelFuture#isSuccess()}
+     * will return <code>true</code>. All {@link ChannelFutureListener} added to it will be notified directly. Also
+     * every call of blocking methods will just return without blocking.
+     */
     ChannelFuture newSucceededFuture();
+
+    /**
+     * Create a new {@link ChannelFuture} which is marked as fakued already. So {@link ChannelFuture#isSuccess()}
+     * will return <code>false</code>. All {@link ChannelFutureListener} added to it will be notified directly. Also
+     * every call of blocking methods will just return without blocking.
+     */
     ChannelFuture newFailedFuture(Throwable cause);
 }

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

@@ -208,12 +208,34 @@ import java.nio.channels.Channels;
  */
 public interface ChannelHandler {
 
+    /**
+     * Gets called before the {@link ChannelHandler} is added to the actual context.
+     */
     void beforeAdd(ChannelHandlerContext ctx) throws Exception;
+
+    /**
+     * Gets called after the {@link ChannelHandler} was added to the actual context.
+     */
     void afterAdd(ChannelHandlerContext ctx) throws Exception;
+
+    /**
+     * Gets called before the {@link ChannelHandler} is removed from the actual context.
+     */
     void beforeRemove(ChannelHandlerContext ctx) throws Exception;
+
+    /**
+     * Gets called after the {@link ChannelHandler} was removed from the actual context.
+     */
     void afterRemove(ChannelHandlerContext ctx) throws Exception;
 
+    /**
+     * Gets called if a {@link Throwable} was thrown.
+     */
     void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception;
+
+    /**
+     * Gets called if an user event was triggered.
+     */
     void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception;
 
     /**

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

@@ -128,34 +128,152 @@ import java.util.Set;
 public interface ChannelHandlerContext
          extends AttributeMap, ChannelFutureFactory,
                  ChannelInboundInvoker, ChannelOutboundInvoker {
+
+    /**
+     * Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}.
+     */
     Channel channel();
+
+    /**
+     * Return the {@link ChannelPipeline} which belongs this {@link ChannelHandlerContext}.
+     */
     ChannelPipeline pipeline();
+
+    /**
+     * The {@link EventExecutor} that is used to dispatch the events. This can also be used to directly
+     * submit tasks that get executed in the event loop. For more informations please refer to the
+     * {@link EventExecutor} javadocs.
+     */
     EventExecutor executor();
 
+    /**
+     * The unique name of the {@link ChannelHandlerContext}.The name was used when then {@link ChannelHandler}
+     * was added to the {@link ChannelPipeline}. This name can also be used to access the registered
+     * {@link ChannelHandler} from the {@link ChannelPipeline}.
+     */
     String name();
+
+    /**
+     * The {@link ChannelHandler} that is bound this {@link ChannelHandlerContext}.
+     */
     ChannelHandler handler();
     Set<ChannelHandlerType> type();
 
+    /**
+     * Return <code>true</code> if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for inbound
+     * which can be used.
+     */
     boolean hasInboundByteBuffer();
+
+    /**
+     * Return <code>true</code> if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for inbound
+     * which can be used.
+     */
     boolean hasInboundMessageBuffer();
+
+    /**
+     * Return the bound {@link ByteBuf} for inbound data if {@link #hasInboundByteBuffer()} returned
+     * <code>true</code>. If {@link #hasInboundByteBuffer()} returned <code>false</code> it will throw a
+     * {@link UnsupportedOperationException}
+     */
     ByteBuf inboundByteBuffer();
+
+    /**
+     * Return the bound {@link MessageBuf} for inbound data if {@link #hasInboundMessageBuffer()} returned
+     * <code>true</code>. If {@link #hasInboundMessageBuffer()} returned <code>false</code> it will throw a
+     * {@link UnsupportedOperationException}.
+     */
     <T> MessageBuf<T> inboundMessageBuffer();
 
+    /**
+     * Return <code>true</code> if the {@link ChannelHandlerContext} has an {@link ByteBuf} bound for outbound
+     * data which can be used.
+     *
+     */
     boolean hasOutboundByteBuffer();
+
+    /**
+     * Return <code>true</code> if the {@link ChannelHandlerContext} has a {@link MessageBuf} bound for outbound
+     * which can be used.
+     */
     boolean hasOutboundMessageBuffer();
+
+    /**
+     * Return the bound {@link ByteBuf} for outbound data if {@link #hasOutboundByteBuffer()} returned
+     * <code>true</code>. If {@link #hasOutboundByteBuffer()} returned <code>false</code> it will throw
+     * a {@link UnsupportedOperationException}.
+     */
     ByteBuf outboundByteBuffer();
+
+    /**
+     * Return the bound {@link MessageBuf} for outbound data if {@link #hasOutboundMessageBuffer()} returned
+     * <code>true</code>. If {@link #hasOutboundMessageBuffer()} returned <code>false</code> it will throw a
+     * {@link UnsupportedOperationException}
+     */
     <T> MessageBuf<T> outboundMessageBuffer();
 
+    /**
+     * Return <code>true</code> if the next {@link ChannelHandlerContext} has a {@link ByteBuf} for handling
+     * inbound data.
+     */
     boolean hasNextInboundByteBuffer();
+
+    /**
+     * Return <code>true</code> if the next {@link ChannelHandlerContext} has a {@link MessageBuf} for handling
+     * inbound data.
+     */
     boolean hasNextInboundMessageBuffer();
+
+    /**
+     * Return the {@link ByteBuf} of the next {@link ChannelHandlerContext} if {@link #hasNextInboundByteBuffer()}
+     * returned <code>true</code>, otherwise a {@link UnsupportedOperationException} is thrown.
+     */
     ByteBuf nextInboundByteBuffer();
+
+    /**
+     * Return the {@link MessageBuf} of the next {@link ChannelHandlerContext} if
+     * {@link #hasNextInboundMessageBuffer()} returned <code>true</code>, otherwise a
+     * {@link UnsupportedOperationException} is thrown.
+     */
     MessageBuf<Object> nextInboundMessageBuffer();
 
+    /**
+     * Return <code>true</code> if the next {@link ChannelHandlerContext} has a {@link ByteBuf} for handling outbound
+     * data.
+     */
     boolean hasNextOutboundByteBuffer();
+
+    /**
+     * Return <code>true</code> if the next {@link ChannelHandlerContext} has a {@link MessageBuf} for handling
+     * outbound data.
+     */
     boolean hasNextOutboundMessageBuffer();
+
+    /**
+     * Return the {@link ByteBuf} of the next {@link ChannelHandlerContext} if {@link #hasNextOutboundByteBuffer()}
+     * returned <code>true</code>, otherwise a {@link UnsupportedOperationException} is thrown.
+     */
     ByteBuf nextOutboundByteBuffer();
+
+    /**
+     * Return the {@link MessageBuf} of the next {@link ChannelHandlerContext} if
+     * {@link #hasNextOutboundMessageBuffer()} returned <code>true</code>, otherwise a
+     * {@link UnsupportedOperationException} is thrown.
+     */
     MessageBuf<Object> nextOutboundMessageBuffer();
 
+    /**
+     * Return <code>true</code> if the {@link ChannelHandlerContext} was marked as readable. This basically means
+     * that once its not readable anymore no new data will be read from the transport and passed down the
+     * {@link ChannelPipeline}.
+     *
+     * Only if all {@link ChannelHandlerContext}'s {@link #isReadable()} return <code>true</code>, the data is
+     * passed again down the {@link ChannelPipeline}.
+     */
     boolean isReadable();
+
+    /**
+     * Mark the {@link ChannelHandlerContext} as readable or suspend it. See {@link #isReadable()}
+     */
     void readable(boolean readable);
 }

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

@@ -15,6 +15,10 @@
  */
 package io.netty.channel;
 
+/**
+ * Define the type of a {@link ChannelHandler}
+ *
+ */
 public enum ChannelHandlerType {
     STATE(0),
     INBOUND(0),
@@ -24,6 +28,9 @@ public enum ChannelHandlerType {
     final int direction; // 0 - up (inbound), 1 - down (outbound)
 
     ChannelHandlerType(int direction) {
+        if (direction != 0 && direction != 1) {
+            throw new IllegalArgumentException("direction must be either 0 or 1");
+        }
         this.direction = direction;
     }
 }

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

@@ -17,6 +17,10 @@ package io.netty.channel;
 
 import io.netty.buffer.ByteBuf;
 
+/**
+ * {@link ChannelInboundHandler} which offers a {@link ByteBuf} to store inbound data in.
+ *
+ */
 public interface ChannelInboundByteHandler extends ChannelInboundHandler {
     @Override
     ByteBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception;

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

@@ -19,9 +19,19 @@ import io.netty.buffer.ByteBuf;
 import io.netty.buffer.Unpooled;
 
 
+/**
+ * Abstract base class for {@link ChannelInboundHandlerAdapter} which should be extended by the user to
+ * get notified once more data is ready to get consumed from the inbound {@link ByteBuf}.
+ *
+ * This implementation is a good starting point for must users.
+ */
 public abstract class ChannelInboundByteHandlerAdapter
         extends ChannelInboundHandlerAdapter implements ChannelInboundByteHandler {
 
+    /**
+     * Create a new unpooled {@link ByteBuf} by default. Sub-classes may override this to offer a more
+     * optimized implementation.
+     */
     @Override
     public ByteBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception {
         return Unpooled.buffer();
@@ -39,5 +49,10 @@ public abstract class ChannelInboundByteHandlerAdapter
         }
     }
 
+    /**
+     * Callback which will get notifed once the given {@link ByteBuf} received more data to read. What will be done
+     * with the data at this point is up to the implementation.
+     * Implementations may choose to read it or just let it in the buffer to read it later.
+     */
     public abstract void inboundBufferUpdated(ChannelHandlerContext ctx, ByteBuf in) throws Exception;
 }

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

@@ -17,6 +17,12 @@ package io.netty.channel;
 
 import io.netty.buffer.ChannelBuf;
 
+/**
+ * {@link ChannelStateHandler} which handles inbound data.
+ */
 public interface ChannelInboundHandler extends ChannelStateHandler {
+    /**
+     * Return the {@link ChannelBuf} which will be used for inbound data for the given {@link ChannelHandlerContext}.
+     */
     ChannelBuf newInboundBuffer(ChannelHandlerContext ctx) throws Exception;
 }

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

@@ -18,6 +18,10 @@ package io.netty.channel;
 
 public abstract class ChannelInboundHandlerAdapter
         extends ChannelStateHandlerAdapter implements ChannelInboundHandler {
+
+    /**
+     * Does nothing by default. Sub-classes may override this if needed.
+     */
     @Override
     public abstract void inboundBufferUpdated(ChannelHandlerContext ctx) throws Exception;
 }

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

@@ -17,7 +17,14 @@ package io.netty.channel;
 
 import io.netty.buffer.MessageBuf;
 
+/**
+ * Special {@link ChannelInboundHandler} which store the inbound data in a {@link MessageBuf} for futher processing.
+ */
 public interface ChannelInboundMessageHandler<I> extends ChannelInboundHandler {
+
+    /**
+     * Return the {@link MessageBuf} which will be used for inbound data to store.
+     */
     @Override
     MessageBuf<I> newInboundBuffer(ChannelHandlerContext ctx) throws Exception;
 }

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

@@ -15,12 +15,23 @@
  */
 package io.netty.channel;
 
+/**
+ * {@link ChannelHandler} which adds callbacks for state changes. This allows the user
+ * to hook in to state changes easily.
+ */
 public interface ChannelStateHandler extends ChannelHandler {
+
     void channelRegistered(ChannelHandlerContext ctx) throws Exception;
     void channelUnregistered(ChannelHandlerContext ctx) throws Exception;
 
     void channelActive(ChannelHandlerContext ctx) throws Exception;
     void channelInactive(ChannelHandlerContext ctx) throws Exception;
 
+    /**
+     * The inbound buffer of the {@link ChannelHandlerContext} was updated with new data.
+     * This means something may be ready to get processed by the actual {@link ChannelStateHandler}
+     * implementation. It's up to the implementation to consume it or keep it in the buffer
+     * to wait for more data and consume it later.
+     */
     void inboundBufferUpdated(ChannelHandlerContext ctx) throws Exception;
 }