From 6c8acb25076048537bcb5d24aa48ba7468058cb0 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Tue, 2 Sep 2008 14:21:40 +0000
Subject: [PATCH] More JavaDoc for Channels

---
 .../netty/channel/ChannelHandlerContext.java  |  8 +++++--
 .../org/jboss/netty/channel/Channels.java     | 23 +++++++++++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java b/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
index 3749ab9b1b..1233174199 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelHandlerContext.java
@@ -67,13 +67,17 @@ public interface ChannelHandlerContext {
 
     /**
      * Sends the specified {@link ChannelEvent} to the next handler in the
-     * {@link ChannelPipeline}.
+     * {@link ChannelPipeline}.  It is always recommended to use the
+     * event generation methods provided by {@link Channels} rather than
+     * calling this method directly by yourself.
      */
     void sendUpstream(ChannelEvent e);
 
     /**
      * Sends the specified {@link ChannelEvent} to the previous handler in the
-     * {@link ChannelPipeline}.
+     * {@link ChannelPipeline}.  It is always recommended to use the
+     * event generation methods provided by {@link Channels} rather than
+     * calling this method directly by yourself.
      */
     void sendDownstream(ChannelEvent e);
 }
\ No newline at end of file
diff --git a/src/main/java/org/jboss/netty/channel/Channels.java b/src/main/java/org/jboss/netty/channel/Channels.java
index 0704851e23..4e630645f0 100644
--- a/src/main/java/org/jboss/netty/channel/Channels.java
+++ b/src/main/java/org/jboss/netty/channel/Channels.java
@@ -30,6 +30,29 @@ import java.util.Map;
  * Provides various factory methods related with {@link Channel} and
  * {@link ChannelPipeline}, and fires an I/O event and request.
  *
+ * <h3>Factory methods</h3>
+ * <p>
+ * It is always recommended to use the factory methods provided by
+ * {@link Channels} rather than calling the constructor of the implementation
+ * types.
+ * <ul>
+ * <li>{@link #pipeline()}</li>
+ * <li>{@link #pipeline(ChannelPipeline)}</li>
+ * <li>{@link #pipelineFactory(ChannelPipeline)}</li>
+ * <li>{@link #succeededFuture(Channel)}</li>
+ * <li>{@link #failedFuture(Channel, Throwable)}</li>
+ * <li>{@link #messageEvent(Channel, ChannelFuture, Object)}</li>
+ * <li>{@link #messageEvent(Channel, ChannelFuture, Object, SocketAddress)}</li>
+ * </ul>
+ *
+ * <h3>Upstream and downstream event generation</h3>
+ * <p>
+ * Various event generation methods are provided to simplify the generation of
+ * upstream events and downstream events.  It is always recommended to use the
+ * event generation methods provided by {@link Channels} rather than calling
+ * {@link ChannelHandlerContext#sendUpstream(ChannelEvent)} or
+ * {@link ChannelHandlerContext#sendDownstream(ChannelEvent)} by yourself.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *