Add javadocs and also some parameter checks in DefaultFileRegion

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

@@ -22,7 +22,7 @@ import io.netty.buffer.ByteBuf;
  * 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.
+ * This implementation is a good starting point for most users.
  */
 public abstract class ChannelInboundByteHandlerAdapter
         extends ChannelInboundHandlerAdapter implements ChannelInboundByteHandler {

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

@@ -16,12 +16,71 @@
 package io.netty.channel;
 
 
+/**
+ * Interface which is shared by others which need to fire inbound events
+ */
 public interface ChannelInboundInvoker {
+
+    /**
+     * A {@link Channel} was registered to its {@link EventLoop}.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#channelRegistered(ChannelHandlerContext)} method
+     * called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireChannelRegistered();
+
+    /**
+     * A {@link Channel} was unregistered from its {@link EventLoop}.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#channelUnregistered(ChannelHandlerContext)} method
+     * called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireChannelUnregistered();
+
+    /**
+     * A {@link Channel} is active now, which means it is connected.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#channelActive(ChannelHandlerContext)} method
+     * called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireChannelActive();
+
+    /**
+     * A {@link Channel} is inactive now, which means it is closed.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#channelInactive(ChannelHandlerContext)} method
+     * called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireChannelInactive();
+
+    /**
+     * A {@link Channel} received an {@link Throwable} in one of its inbound operations.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#exceptionCaught(ChannelHandlerContext, Throwable)}
+     * method  called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireExceptionCaught(Throwable cause);
+
+    /**
+     * A {@link Channel} received an user defined event.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object)}
+     * method  called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireUserEventTriggered(Object event);
+
+    /**
+     * A {@link Channel} received bytes which are now ready to read from its inbound buffer.
+     *
+     * This will result in having the  {@link ChannelInboundHandler#inboundBufferUpdated(ChannelHandlerContext)}
+     * method  called of the next  {@link ChannelInboundHandler} contained in the  {@link ChannelPipeline} of the
+     * {@link Channel}.
+     */
     void fireInboundBufferUpdated();
 }

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

@@ -15,15 +15,36 @@
  */
 package io.netty.channel;
 
+import io.netty.bootstrap.Bootstrap;
+import io.netty.bootstrap.ServerBootstrap;
 import io.netty.channel.ChannelHandler.Sharable;
 import io.netty.logging.InternalLogger;
 import io.netty.logging.InternalLoggerFactory;
 
+/**
+ * A special {@link ChannelStateHandler} which offers an easy way to initialize a {@link Channel} once it was
+ * registered to its {@link EventLoop}.
+ *
+ * Implementations are most often used in the context of {@link Bootstrap#handler(ChannelHandler)} ,
+ * {@link ServerBootstrap#handler(ChannelHandler)} and {@link ServerBootstrap#childHandler(ChannelHandler)} to
+ * setup the {@link ChannelPipeline} of a {@link Channel}.
+ *
+ * Be aware that this class is marked as {@link Sharable} and so the implementation must be safe to be re-used.
+ *
+ * @param <C>   A sub-type of {@link Channel}
+ */
 @Sharable
 public abstract class ChannelInitializer<C extends Channel> extends ChannelStateHandlerAdapter {
 
     private static final InternalLogger logger = InternalLoggerFactory.getInstance(ChannelInitializer.class);
 
+    /**
+     * This method will be called once the {@link Channel} was registered. After the method returns this instance
+     * will be removed from the {@link ChannelPipeline} of the {@link Channel}.
+     *
+     * @param ch            the {@link Channel} which was registered.
+     * @throws Exception    is thrown if an error accours. In that case the {@link Channel} will be closed.
+     */
     public abstract void initChannel(C ch) throws Exception;
 
     @SuppressWarnings("unchecked")

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

@@ -27,6 +27,14 @@ public final class ChannelMetadata {
     private final BufType bufferType;
     private final boolean hasDisconnect;
 
+    /**
+     * Create a new instance
+     *
+     * @param bufferType        the {@link BufType} which will be used by the {@link Channel}.
+     * @param hasDisconnect     {@code true} if and only if the channel has the {@code disconnect()} operation
+     *                          that allows a user to disconnect and then call {@link Channel#connect(SocketAddress)}
+     *                                      again, such as UDP/IP.
+     */
     public ChannelMetadata(BufType bufferType, boolean hasDisconnect) {
         if (bufferType == null) {
             throw new NullPointerException("bufferType");
@@ -36,6 +44,9 @@ public final class ChannelMetadata {
         this.hasDisconnect = hasDisconnect;
     }
 
+    /**
+     * Returns the {@link BufType} which will be used by the {@link Channel}.
+     */
     public BufType bufferType() {
         return bufferType;
     }

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

@@ -17,7 +17,13 @@ package io.netty.channel;
 
 import io.netty.buffer.Buf;
 
+/**
+ * {@link ChannelOperationHandler} which handles outbound data.
+ */
 public interface ChannelOutboundHandler extends ChannelOperationHandler {
+    /**
+     * Return the {@link Buf} which will be used for outbound data for the given {@link ChannelHandlerContext}.
+     */
     Buf newOutboundBuffer(ChannelHandlerContext ctx) throws Exception;
 
     /**

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

@@ -15,6 +15,7 @@
  */
 package io.netty.channel;
 
+import io.netty.buffer.ByteBuf;
 import io.netty.buffer.ByteBufAllocator;
 
 /**
@@ -22,8 +23,14 @@ import io.netty.buffer.ByteBufAllocator;
  */
 interface ChannelPropertyAccess {
 
+    /**
+     * Return the assigned {@link ChannelPipeline}
+     */
     ChannelPipeline pipeline();
 
+    /**
+     * Return the assigned {@link ByteBufAllocator} which will be used for allocate {@link ByteBuf}s.
+     */
     ByteBufAllocator alloc();
 
     /**

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

@@ -22,6 +22,9 @@ import java.nio.channels.WritableByteChannel;
 import io.netty.logging.InternalLogger;
 import io.netty.logging.InternalLoggerFactory;
 
+/**
+ * Default {@link FileRegion} implementation which transfer data from a {@link FileChannel}.
+ */
 public class DefaultFileRegion implements FileRegion {
 
     private static final InternalLogger logger = InternalLoggerFactory.getInstance(DefaultFileRegion.class);
@@ -30,7 +33,23 @@ public class DefaultFileRegion implements FileRegion {
     private final long position;
     private final long count;
 
+    /**
+     * Create a new instance
+     *
+     * @param file      the {@link FileChannel} which should be transfered
+     * @param position  the position from which the transfer should start
+     * @param count     the number of bytes to transfer
+     */
     public DefaultFileRegion(FileChannel file, long position, long count) {
+        if (file == null) {
+            throw new NullPointerException("file");
+        }
+        if (position < 0) {
+            throw new IllegalArgumentException("position must be >= 0 but was " + position);
+        }
+        if (count <= 0) {
+            throw new IllegalArgumentException("count must be >= 0 but was " + count);
+        }
         this.file = file;
         this.position = position;
         this.count = count;