Next round of javadocs cleanup and fixes. Also limit the visibility of FailedChannelFuture

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

@@ -17,8 +17,7 @@ package io.netty.channel;
 
 /**
  * A {@link ChannelException} which is thrown when a {@link ChannelPipeline}
- * failed to process a {@link ChannelEvent} or when a {@link ChannelPipelineFactory}
+ * failed to execute an operation.
- * failed to initialize a {@link ChannelPipeline}.
  *
  * @apiviz.exclude
  */

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

@@ -30,10 +30,8 @@ import java.util.concurrent.TimeoutException;
 import static java.util.concurrent.TimeUnit.*;
 
 /**
- * The default {@link ChannelFuture} implementation.  It is recommended to
+ * The default {@link ChannelFuture} implementation.  It is recommended to use {@link Channel#newFuture()} to create
- * use {@link Channels#future(Channel)} and {@link Channels#future(Channel, boolean)}
+ * a new {@link ChannelFuture} rather than calling the constructor explicitly.
- * to create a new {@link ChannelFuture} rather than calling the constructor
- * explicitly.
  */
 public class DefaultChannelFuture extends FlushCheckpoint implements ChannelFuture {
 

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

@@ -24,6 +24,9 @@ import java.util.concurrent.ThreadFactory;
  */
 class DefaultEventExecutor extends SingleThreadEventExecutor {
 
+    /**
+     * @see SingleThreadEventExecutor#SingleThreadEventExecutor(EventExecutorGroup, ThreadFactory, ChannelTaskScheduler)
+     */
     DefaultEventExecutor(
             DefaultEventExecutorGroup parent, ThreadFactory threadFactory, ChannelTaskScheduler scheduler) {
         super(parent, threadFactory, scheduler);

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

@@ -17,12 +17,22 @@ package io.netty.channel;
 
 import java.util.concurrent.ThreadFactory;
 
+/**
+ * Default implementation of {@link MultithreadEventExecutorGroup} which will use {@link DefaultEventExecutor} instances
+ * to handle the tasks.
+ */
 public class DefaultEventExecutorGroup extends MultithreadEventExecutorGroup {
 
+    /**
+     * @see MultithreadEventExecutorGroup#MultithreadEventExecutorGroup(int, ThreadFactory, Object...)
+     */
     public DefaultEventExecutorGroup(int nThreads) {
         this(nThreads, null);
     }
 
+    /**
+     * @see MultithreadEventExecutorGroup#MultithreadEventExecutorGroup(int, ThreadFactory, Object...)
+     */
     public DefaultEventExecutorGroup(int nThreads, ThreadFactory threadFactory) {
         super(nThreads, threadFactory);
     }

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

@@ -34,8 +34,6 @@ public interface EventExecutor extends EventExecutorGroup, ScheduledExecutorServ
 
     /**
      * Return the {@link EventExecutorGroup} which is the parent of this {@link EventExecutor},
-     * or {@code null} if it has no parent
-
      */
     EventExecutorGroup parent();
 

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

@@ -15,6 +15,13 @@
  */
 package io.netty.channel;
 
+/**
+ * Will handle all the I/O-Operations for a {@link Channel} once it was registered.
+ *
+ * One {@link EventLoop} instance will usually handle more then one {@link Channel} but this may depend on
+ * implementation details and internals.
+ *
+ */
 public interface EventLoop extends EventExecutor, EventLoopGroup {
     @Override
     EventLoopGroup parent();

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

@@ -15,6 +15,10 @@
  */
 package io.netty.channel;
 
+/**
+ * Special {@link ChannelException} which will be thrown by {@link EventLoop} and {@link EventLoopGroup}
+ * implementations when an error accours.
+ */
 public class EventLoopException extends ChannelException {
 
     private static final long serialVersionUID = -8969100344583703616L;

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

@@ -22,7 +22,7 @@ import java.util.concurrent.TimeoutException;
 
 /**
  * The {@link CompleteChannelFuture} which is failed already.  It is
- * recommended to use {@link Channels#failedFuture(Channel, Throwable)}
+ * recommended to use {@link Channel#newFailedFuture(Throwable)}
  * instead of calling the constructor of this future.
  */
 public class FailedChannelFuture extends CompleteChannelFuture {

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

@@ -75,7 +75,7 @@ public interface FileRegion {
     long transferTo(WritableByteChannel target, long position) throws IOException;
 
     /**
-     * Close the {@link FileRegion}.
+     * Close the {@link FileRegion}. After calling this method accessing the {@link FileRegion} may fail.
      */
     void close();
 }

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

@@ -22,15 +22,29 @@ import java.util.concurrent.ThreadFactory;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
+/**
+ * Abstract base class for {@link EventExecutorGroup} implementations that handles their tasks with multiple threads at
+ * the same time.
+ */
 public abstract class MultithreadEventExecutorGroup implements EventExecutorGroup {
 
-    private static final int DEFAULT_POOL_SIZE = Runtime.getRuntime().availableProcessors() * 2;
+    public static final int DEFAULT_POOL_SIZE = Runtime.getRuntime().availableProcessors() * 2;
     private static final AtomicInteger poolId = new AtomicInteger();
 
     final ChannelTaskScheduler scheduler;
     private final EventExecutor[] children;
     private final AtomicInteger childIndex = new AtomicInteger();
 
+    /**
+     * Create a new intance
+     *
+     * @param nThreads          the number of threads that will be used by this instance. Use 0 for the default number
+     *                          of {@link #DEFAULT_POOL_SIZE}
+     * @param threadFactory     the ThreadFactory to use, or {@code null} if the default should be used.
+     * @param args              arguments which will passed to each
+     *                          {@link #newChild(java.util.concurrent.ThreadFactory, ChannelTaskScheduler, Object...)}
+     *                          call.
+     */
     protected MultithreadEventExecutorGroup(int nThreads, ThreadFactory threadFactory, Object... args) {
         if (nThreads < 0) {
             throw new IllegalArgumentException(String.format(
@@ -75,6 +89,11 @@ public abstract class MultithreadEventExecutorGroup implements EventExecutorGrou
         return children;
     }
 
+    /**
+     * Create a new EventExecutor which will later then accessable via the {@link #next()}  method. This method will be
+     * called for each thread that will serve this {@link MultithreadEventExecutorGroup}.
+     *
+     */
     protected abstract EventExecutor newChild(
             ThreadFactory threadFactory, ChannelTaskScheduler scheduler, Object... args) throws Exception;
 

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

@@ -17,8 +17,15 @@ package io.netty.channel;
 
 import java.util.concurrent.ThreadFactory;
 
+/**
+ * Abstract base class for {@link EventLoopGroup} implementations that handles their tasks with multiple threads at
+ * the same time.
+ */
 public abstract class MultithreadEventLoopGroup extends MultithreadEventExecutorGroup implements EventLoopGroup {
 
+    /**
+     * @see #MultithreadEventLoopGroup(int, java.util.concurrent.ThreadFactory, Object...)
+     */
     protected MultithreadEventLoopGroup(int nThreads, ThreadFactory threadFactory,
             Object... args) {
         super(nThreads, threadFactory, args);

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

@@ -64,6 +64,9 @@ public abstract class SingleThreadEventExecutor extends AbstractExecutorService
         }
     };
 
+    /**
+     * Return the {@link SingleThreadEventExecutor} which belongs the current {@link Thread}.
+     */
     public static SingleThreadEventExecutor currentEventLoop() {
         return CURRENT_EVENT_LOOP.get();
     }
@@ -78,6 +81,14 @@ public abstract class SingleThreadEventExecutor extends AbstractExecutorService
     private volatile int state = ST_NOT_STARTED;
     private long lastAccessTimeNanos;
 
+    /**
+     * Create a new instance
+     *
+     * @param parent            the {@link EventExecutorGroup} which is the parent of this instance and belongs to it
+     * @param threadFactory     the {@link ThreadFactory} which will be used for the used {@link Thread}
+     * @param scheduler         the {@link ChannelTaskScheduler} which will be used to schedule Tasks for later
+     *                          execution
+     */
     protected SingleThreadEventExecutor(
             EventExecutorGroup parent, ThreadFactory threadFactory, ChannelTaskScheduler scheduler) {
         if (threadFactory == null) {

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

@@ -17,8 +17,16 @@ package io.netty.channel;
 
 import java.util.concurrent.ThreadFactory;
 
+/**
+ * Abstract base class for {@link EventLoop}'s that execute all its submitted tasks in a single thread.
+ *
+ */
 public abstract class SingleThreadEventLoop extends SingleThreadEventExecutor implements EventLoop {
 
+    /**
+     *
+     * @see SingleThreadEventExecutor#SingleThreadEventExecutor(EventExecutorGroup, ThreadFactory, ChannelTaskScheduler)
+     */
     protected SingleThreadEventLoop(
             EventLoopGroup parent, ThreadFactory threadFactory, ChannelTaskScheduler scheduler) {
         super(parent, threadFactory, scheduler);

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

@@ -15,14 +15,13 @@
  */
 package io.netty.channel;
 
-import java.nio.channels.Channels;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
 /**
  * The {@link CompleteChannelFuture} which is succeeded already.  It is
- * recommended to use {@link Channels#succeededFuture(Channel)} instead of
+ * recommended to use {@link Channel#newSucceededFuture()} instead of
  * calling the constructor of this future.
  */
 public class SucceededChannelFuture extends CompleteChannelFuture {

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

@@ -19,7 +19,7 @@ import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
-public class VoidChannelFuture implements ChannelFuture.Unsafe {
+class VoidChannelFuture implements ChannelFuture.Unsafe {
 
     private final Channel channel;