From 6321bb406fda0a44bb7e372b8921e31a4c521183 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Thu, 23 Jul 2009 08:26:54 +0000
Subject: [PATCH] More Javadoc

---
 .../java/org/jboss/netty/channel/Channel.java | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/jboss/netty/channel/Channel.java b/src/main/java/org/jboss/netty/channel/Channel.java
index b8ffe25f1e..6a1361c608 100644
--- a/src/main/java/org/jboss/netty/channel/Channel.java
+++ b/src/main/java/org/jboss/netty/channel/Channel.java
@@ -26,6 +26,8 @@ import java.net.InetSocketAddress;
 import java.net.SocketAddress;
 
 import org.jboss.netty.channel.socket.DatagramChannel;
+import org.jboss.netty.channel.socket.ServerSocketChannel;
+import org.jboss.netty.channel.socket.SocketChannel;
 
 
 /**
@@ -42,13 +44,26 @@ import org.jboss.netty.channel.socket.DatagramChannel;
  * </ul>
  *
  * <h3>All I/O operations are asynchronous.</h3>
- *
+ * <p>
  * All I/O operations in Netty are asynchronous.  It means any I/O calls will
  * return immediately with no guarantee that the requested I/O operation has
  * been completed at the end of the call.  Instead, you will be returned with
- * a {@link ChannelFuture} instance which tells you when the requested I/O
+ * a {@link ChannelFuture} instance which will notify you when the requested I/O
  * operation has succeeded, failed, or canceled.
  *
+ * <h3>Channels are hierarchical</h3>
+ * <p>
+ * A {@link Channel} can have a {@linkplain #getParent() parent} depending on
+ * how it was created.  For instance, a {@link SocketChannel}, that was accepted
+ * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
+ * as its parent on {@link #getParent()}.
+ * <p>
+ * The semantics of the hierarchical structure depends on the transport
+ * implementation where the {@link Channel} belongs to.  For example, you could
+ * write a new {@link Channel} implementation that creates the sub-channels that
+ * share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
+ * <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *