Added JavaDoc for ChannelFuture and its related types

src/main/java/org/jboss/netty/channel/ChannelFuture.java

@@ -25,6 +25,11 @@ package org.jboss.netty.channel;
 import java.util.concurrent.TimeUnit;
 
 /**
+ * The result of an asynchronous {@link Channel} I/O operation.  Methods are
+ * provided to check if the I/O operation is complete, to wait for its
+ * completion, and to retrieve the result of the I/O operation. It also allows
+ * you to add more than one {@link ChannelFutureListener} so you can get
+ * notified when the I/O operation is complete.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -35,25 +40,125 @@ import java.util.concurrent.TimeUnit;
  * @apiviz.owns org.jboss.netty.channel.ChannelFutureListener - - notifies
  */
 public interface ChannelFuture {
+
+    /**
+     * Returns a channel where the I/O operation associated with this future
+     * takes place.
+     */
     Channel getChannel();
 
+    /**
+     * Returns {@code true} if and only if this future is complete, regardless
+     * the operation was successful, failed, or canceled.
+     */
     boolean isDone();
+
+    /**
+     * Returns {@code true} if and only if this future was canceled by
+     * a {@link #cancel()} method.
+     */
     boolean isCancelled();
+
+    /**
+     * Returns {@code true} if and only if the I/O operation was done
+     * successfully.
+     */
     boolean isSuccess();
+
+    /**
+     * Returns the cause of the failed I/O operation if the I/O operation has
+     * failed.
+     *
+     * @return the cause of the failure.
+     *         {@code null} if succeeded or this future is not done yet.
+     */
     Throwable getCause();
 
+    /**
+     * Cancels the I/O operation associated with this future and notifies all
+     * listeners if canceled successfully.
+     *
+     * @return {@code true} if and only if the operation has been canceled.
+     *         {@code false} if the operation can't be canceled or is already done.
+     */
     boolean cancel();
 
+    /**
+     * Marks this future as a success and notifies all listeners.
+     */
     void setSuccess();
+
+    /**
+     * Marks this future as a failure and notifies all listeners.
+     */
     void setFailure(Throwable cause);
 
+    /**
+     * Adds the specified listener to this future.  The specified listener is
+     * notified when this future is {@linkplain #isDone() done}.  If this
+     * future is already done, the specified listener is notified immediately.
+     */
     void addListener(ChannelFutureListener listener);
+
+    /**
+     * Removes the specified listener from this future.  The specified
+     * listener is no longer notified when this future is
+     * {@linkplain #isDone() done}.  If this future is already done, this
+     * method has no effect and returns silently.
+     */
     void removeListener(ChannelFutureListener listener);
 
+    /**
+     * Waits for this future to be done.
+     *
+     * @throws InterruptedException
+     *         if the current thread was interrupted
+     */
     ChannelFuture await() throws InterruptedException;
+
+    /**
+     * Waits for this future to be done uninterruptibly.  This method catches
+     * an {@link InterruptedException} and discards it silently.
+     */
     ChannelFuture awaitUninterruptibly();
+
+    /**
+     * Waits for this future to be done with the specified time limit.
+     *
+     * @return {@code true} if and only if the future was done within
+     *         the specified time limit
+     *
+     * @throws InterruptedException
+     *         if the current thread was interrupted
+     */
     boolean await(long timeout, TimeUnit unit) throws InterruptedException;
+
+    /**
+     * Waits for this future to be done with the specified time limit.
+     *
+     * @return {@code true} if and only if the future was done within
+     *         the specified time limit
+     *
+     * @throws InterruptedException
+     *         if the current thread was interrupted
+     */
     boolean await(long timeoutMillis) throws InterruptedException;
+
+    /**
+     * Waits for this future to be done with the specified time limit.  This
+     * method catches an {@link InterruptedException} and discards it silently.
+     *
+     * @return {@code true} if and only if the future was done within
+     *         the specified time limit
+     */
     boolean awaitUninterruptibly(long timeout, TimeUnit unit);
+
+    /**
+     * Waits for this future to be done with the specified time limit.  This
+     * method catches an {@link InterruptedException} and discards it silently.
+     *
+     * @return {@code true} if and only if the future was done within
+     *         the specified time limit
+     */
     boolean awaitUninterruptibly(long timeoutMillis);
 }

src/main/java/org/jboss/netty/channel/ChannelFutureListener.java

@@ -25,6 +25,9 @@ package org.jboss.netty.channel;
 import java.util.EventListener;
 
 /**
+ * Listens to the result of an asynchronous I/O operation.  The result of the
+ * I/O operation is notified by {@link ChannelFuture} once this listener is
+ * added to the future.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -34,6 +37,7 @@ import java.util.EventListener;
  * @apiviz.landmark
  */
 public interface ChannelFutureListener extends EventListener {
+
     /**
      * An {@link ChannelFutureListener} that closes the {@link Channel} which is
      * associated with the specified {@link ChannelFuture}.
@@ -45,7 +49,7 @@ public interface ChannelFutureListener extends EventListener {
     };
 
     /**
-     * Invoked when the operation associated with the {@link ChannelFuture}
+     * Invoked when the I/O operation associated with the {@link ChannelFuture}
      * has been completed.
      *
      * @param future  The source {@link ChannelFuture} which called this

src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java

@@ -27,6 +27,15 @@ import java.util.concurrent.TimeUnit;
 import org.jboss.netty.logging.InternalLogger;
 import org.jboss.netty.logging.InternalLoggerFactory;
 
+/**
+ * Skeletal {@link ChannelFuture} implementation which represents a future
+ * which is complete (done) already.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ */
 public abstract class CompleteChannelFuture implements ChannelFuture {
 
     private static final InternalLogger logger =
@@ -34,6 +43,11 @@ public abstract class CompleteChannelFuture implements ChannelFuture {
 
     private final Channel channel;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param channel the {@link Channel} associated with this future
+     */
     protected CompleteChannelFuture(Channel channel) {
         if (channel == null) {
             throw new NullPointerException("channel");

src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java

@@ -29,11 +29,19 @@ import java.util.concurrent.TimeUnit;
 import org.jboss.netty.logging.InternalLogger;
 import org.jboss.netty.logging.InternalLoggerFactory;
 
-
+/**
+ * The default {@link ChannelFuture} implementation.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ */
 public class DefaultChannelFuture implements ChannelFuture {
 
     private static final InternalLogger logger =
         InternalLoggerFactory.getInstance(DefaultChannelFuture.class);
+
     private static final int DEAD_LOCK_CHECK_INTERVAL = 5000;
     private static final Throwable CANCELLED = new Throwable();
 
@@ -46,6 +54,14 @@ public class DefaultChannelFuture implements ChannelFuture {
     private Throwable cause;
     private int waiters;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param channel
+     *        the {@link Channel} associated with this future
+     * @param cancellable
+     *        {@code true} if and only if this future can be canceled
+     */
     public DefaultChannelFuture(Channel channel, boolean cancellable) {
         this.channel = channel;
         this.cancellable = cancellable;

src/main/java/org/jboss/netty/channel/FailedChannelFuture.java

@@ -22,11 +22,26 @@
  */
 package org.jboss.netty.channel;
 
-
+/**
+ * The {@link CompleteChannelFuture} which is failed already.  It is
+ * recommended to use {@link Channels#failedFuture(Channel, Throwable)}
+ * instead of calling the constructor of this future.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ */
 public class FailedChannelFuture extends CompleteChannelFuture {
 
     private final Throwable cause;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param channel the {@link Channel} associated with this future
+     * @param cause   the cause of failure
+     */
     public FailedChannelFuture(Channel channel, Throwable cause) {
         super(channel);
         if (cause == null) {

src/main/java/org/jboss/netty/channel/SucceededChannelFuture.java

@@ -22,9 +22,23 @@
  */
 package org.jboss.netty.channel;
 
-
+/**
+ * The {@link CompleteChannelFuture} which is succeeded already.  It is
+ * recommended to use {@link Channels#succeededFuture(Channel)} instead of
+ * calling the constructor of this future.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ */
 public class SucceededChannelFuture extends CompleteChannelFuture {
 
+    /**
+     * Creates a new instance.
+     *
+     * @param channel the {@link Channel} associated with this future
+     */
     public SucceededChannelFuture(Channel channel) {
         super(channel);
     }