From c05a337d7475e4a66da6563ebb339addc5a10356 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Tue, 2 Sep 2008 14:12:56 +0000
Subject: [PATCH] Added some links into the example code

---
 .../netty/bootstrap/ClientBootstrap.java      |  7 ++---
 .../netty/bootstrap/ServerBootstrap.java      |  7 ++---
 .../channel/ChannelDownstreamHandler.java     | 22 +++++++++++-----
 .../org/jboss/netty/channel/ChannelEvent.java |  2 ++
 .../jboss/netty/channel/ChannelHandler.java   | 17 ++++++++----
 .../jboss/netty/channel/ChannelPipeline.java  | 13 ++++++++++
 .../netty/channel/ChannelUpstreamHandler.java | 26 ++++++++++++-------
 .../netty/channel/SimpleChannelHandler.java   |  3 +--
 .../netty/logging/InternalLoggerFactory.java  |  2 +-
 9 files changed, 69 insertions(+), 30 deletions(-)

diff --git a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java
index f5e73a611e..959557cf97 100644
--- a/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java
+++ b/src/main/java/org/jboss/netty/bootstrap/ClientBootstrap.java
@@ -24,6 +24,7 @@ package org.jboss.netty.bootstrap;
 
 import static org.jboss.netty.channel.Channels.*;
 
+import java.net.InetSocketAddress;
 import java.net.SocketAddress;
 import java.util.concurrent.BlockingQueue;
 import java.util.concurrent.LinkedBlockingQueue;
@@ -53,7 +54,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * ClientBootstrap b = ...;
  *
  * // Options for a new channel
- * b.setOption("remoteAddress", new InetSocketAddress("example.com", 8080));
+ * b.setOption("remoteAddress", new {@link InetSocketAddress}("example.com", 8080));
  * b.setOption("tcpNoDelay", true);
  * b.setOption("receiveBufferSize", 1048576);
  * </pre>
@@ -68,7 +69,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  *
  * <pre>
  * ClientBootstrap b = ...;
- * ChannelPipeline p = b.getPipeline();
+ * {@link ChannelPipeline} p = b.getPipeline();
  *
  * // Add handlers to the pipeline.
  * p.addLast("encoder", new EncodingHandler());
@@ -84,7 +85,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * ClientBootstrap b = ...;
  * b.setPipelineFactory(new MyPipelineFactory());
  *
- * public class MyPipelineFactory implements ChannelPipelineFactory {
+ * public class MyPipelineFactory implements {@link ChannelPipelineFactory} {
  *   // Create a new pipeline for a new channel and configure it here ...
  * }
  * </pre>
diff --git a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java
index 97492e9122..10bbea5692 100644
--- a/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java
+++ b/src/main/java/org/jboss/netty/bootstrap/ServerBootstrap.java
@@ -24,6 +24,7 @@ package org.jboss.netty.bootstrap;
 
 import static org.jboss.netty.channel.Channels.*;
 
+import java.net.InetSocketAddress;
 import java.net.SocketAddress;
 import java.util.HashMap;
 import java.util.Map;
@@ -71,7 +72,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * ServerBootstrap b = ...;
  *
  * // Options for a parent channel
- * b.setOption("localAddress", new InetSocketAddress(8080));
+ * b.setOption("localAddress", new {@link InetSocketAddress}(8080));
  * b.setOption("reuseAddress", true);
  *
  * // Options for its children
@@ -102,7 +103,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  *
  * <pre>
  * ServerBootstrap b = ...;
- * ChannelPipeline p = b.getPipeline();
+ * {@link ChannelPipeline} p = b.getPipeline();
  *
  * // Add handlers to the pipeline.
  * p.addLast("encoder", new EncodingHandler());
@@ -118,7 +119,7 @@ import org.jboss.netty.channel.SimpleChannelHandler;
  * ServerBootstrap b = ...;
  * b.setPipelineFactory(new MyPipelineFactory());
  *
- * public class MyPipelineFactory implements ChannelPipelineFactory {
+ * public class MyPipelineFactory implements {@link ChannelPipelineFactory} {
  *   // Create a new pipeline for a new child channel and configure it here ...
  * }
  * </pre>
diff --git a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
index fc08b76f95..2dd5a6e538 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
@@ -29,6 +29,8 @@ import java.net.SocketAddress;
  * Handles or intercepts a downstream {@link ChannelEvent}, and fires a
  * {@link ChannelEvent} to the previous or next handler in a
  * {@link ChannelPipeline}.
+ *
+ * <h3>Downstream events</h3>
  * <p>
  * A downstream event is an event which is supposed to be processed from the
  * last handler to the first handler in the {@link ChannelPipeline}.
@@ -70,11 +72,15 @@ import java.net.SocketAddress;
  * </table>
  * <p>
  * Other event types and conditions which were not addressed here will be
- * ignored and discarded.  You also might want to refer to {@link ChannelUpstreamHandler}
- * to see how a {@link ChannelEvent} is interpreted when going upstream.  Also,
- * please refer to the {@link ChannelEvent} documentation to find out what a
- * upstream event and a downstream event are and what fundamental differences
- * they have, if you didn't read yet.
+ * ignored and discarded.
+ *
+ * <h4>Additional resources worth reading</h4>
+ * <p>
+ * You might want to refer to {@link ChannelUpstreamHandler} to see how a
+ * {@link ChannelEvent} is interpreted when going upstream.  Also, please refer
+ * to the {@link ChannelEvent} documentation to find out what a upstream event
+ * and a downstream event are and what fundamental differences they have, if
+ * you didn't read yet.
  *
  * <h3>Firing an event to the previous or next handler</h3>
  * <p>
@@ -85,19 +91,21 @@ import java.net.SocketAddress;
  *
  * <pre>
  * // Sending the event forward (downstream)
- * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
  *     ...
  *     ctx.sendDownstream(e);
  *     ...
  * }
  *
  * // Sending the event backward (upstream)
- * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
  *     ...
  *     ctx.sendUpstream(new DefaultChannelStateEvent(...));
  *     ...
  * }
  * </pre>
+ *
+ * <h4>Using the helper class to fire an event</h4>
  * <p>
  * You will also find various helper methods in {@link Channels} to be useful
  * to generate and fire an artificial or manipulated event.
diff --git a/src/main/java/org/jboss/netty/channel/ChannelEvent.java b/src/main/java/org/jboss/netty/channel/ChannelEvent.java
index 6c524061c9..faf6aa8ede 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelEvent.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelEvent.java
@@ -46,6 +46,8 @@ package org.jboss.netty.channel;
  * in the future.  For example, a {@link MessageEvent} represents the
  * notification of a received message when it goes upstream, while it
  * represents the request of writing a message when it goes downstream.
+ *
+ * <h4>Additional resources worth reading</h4>
  * <p>
  * Please refer to the documentation of {@link ChannelHandler} and its sub-types
  * ({@link ChannelUpstreamHandler} for upstream events and
diff --git a/src/main/java/org/jboss/netty/channel/ChannelHandler.java b/src/main/java/org/jboss/netty/channel/ChannelHandler.java
index b8f80762da..ee19bbb288 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelHandler.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelHandler.java
@@ -26,17 +26,18 @@ package org.jboss.netty.channel;
  * Handles or intercepts a {@link ChannelEvent}, and fires a
  * {@link ChannelEvent} to the next or previous handler in a
  * {@link ChannelPipeline}.
+ *
+ * <h3>Sub-types</h3>
  * <p>
  * This is a tag interface.  There are two sub-interfaces which processes
  * a received event actually, one for upstream events and the other for
  * downstream events:
  * <ul>
- * <li>{@link ChannelUpstreamHandler} handles and intercepts
- *     a {@link ChannelEvent} fired by an I/O thread.</li>
- * <li>{@link ChannelDownstreamHandler} handles and intercepts
- *     a {@link ChannelEvent} fired by a user via the methods in
- *     the {@link Channel} interface and the {@link Channels} helper class.</li>
+ * <li>{@link ChannelUpstreamHandler} handles and intercepts a upstream {@link ChannelEvent}.</li>
+ * <li>{@link ChannelDownstreamHandler} handles and intercepts a downstream {@link ChannelEvent}.</li>
  * </ul>
+ *
+ * <h3>The context object</h3>
  * <p>
  * A {@link ChannelHandler} is provided with a {@link ChannelHandlerContext}
  * object.  The {@link ChannelHandler} is supposed to interact with the
@@ -45,6 +46,12 @@ package org.jboss.netty.channel;
  * or previous handler or modify the behavior of the pipeline by adding or
  * removing a handler for example.
  *
+ * <h3>Additional resources worth reading</h3>
+ * <p>
+ * Please refer to the {@link ChannelEvent} documentation to find out what a
+ * upstream event and a downstream event are and what fundamental differences
+ * they have, if you didn't read yet.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
diff --git a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
index daca62abec..f77fef177f 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelPipeline.java
@@ -27,6 +27,7 @@ import java.util.NoSuchElementException;
 
 import org.jboss.netty.buffer.ChannelBuffer;
 import org.jboss.netty.handler.execution.ExecutionHandler;
+import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
 import org.jboss.netty.handler.ssl.SslHandler;
 
 
@@ -38,6 +39,8 @@ import org.jboss.netty.handler.ssl.SslHandler;
  * <a href="http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html">Intercepting
  * Filter</a> pattern to give a user full control over how an event is handled
  * and how the {@link ChannelHandler}s in the pipeline interact with each other.
+ *
+ * <h3>Building a pipeline</h3>
  * <p>
  * A user is supposed to have one or more {@link ChannelHandler}s in a
  * pipeline to receive I/O events (e.g. read) and to request I/O operations
@@ -54,6 +57,16 @@ import org.jboss.netty.handler.ssl.SslHandler;
  *                              (e.g. database access).</li>
  * </ol>
  *
+ * and it could be represented as shown in the following example:
+ *
+ * <pre>
+ * ChannelPipeline pipeline = {@link Channels#pipeline() Channels.pipeline()};
+ * pipeline.addLast("decoder", new MyProtocolDecoder());
+ * pipeline.addLast("encoder", new MyProtocolEncoder());
+ * pipeline.addLast("executor", new {@link ExecutionHandler}(new {@link OrderedMemoryAwareThreadPoolExecutor}(16, 1048576, 1048576)));
+ * pipeline.addLast("handler", new MyBusinessLogicHandler());
+ * </pre>
+ *
  * <h3>Thread safety</h3>
  * <p>
  * A {@link ChannelHandler} can be added or removed at any time because a
diff --git a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
index 862ea735eb..2df047249b 100644
--- a/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
+++ b/src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
@@ -35,12 +35,14 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * Handles or intercepts a upstream {@link ChannelEvent}, and fires a
  * {@link ChannelEvent} to the next or previous handler in a
  * {@link ChannelPipeline}.
+ *
+ * <h3>Upstream events</h3>
  * <p>
  * A upstream event is an event which is supposed to be processed from the
  * first handler to the last handler in the {@link ChannelPipeline}.
  * For example, all events fired by an I/O thread are upstream events, and
  * they have the following meaning:
- *
+ * <p>
  * <table border="1" cellspacing="0" cellpadding="6">
  * <tr>
  * <th>Event name</th></th><th>Event type and condition</th><th>Meaning</th>
@@ -94,7 +96,7 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * <p>
  * These two additional event types are used only for a parent channel which
  * can have a child channel (e.g. {@link ServerSocketChannel}).
- *
+ * <p>
  * <table border="1" cellspacing="0" cellpadding="6">
  * <tr>
  * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
@@ -110,12 +112,16 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  * <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
  * </tr>
  * </table>
+ *
+ * <h4>Additional resources worth reading</h4>
  * <p>
- * You also might want to refer to {@link ChannelDownstreamHandler} to see
- * how a {@link ChannelEvent} is interpreted when going downstream.  Also,
- * please refer to the {@link ChannelEvent} documentation to find out what a
- * upstream event and a downstream event are and what fundamental differences
- * they have, if you didn't read yet.
+ * You might want to refer to {@link ChannelDownstreamHandler} to see how a
+ * {@link ChannelEvent} is interpreted when going downstream.  Also, please
+ * refer to the {@link ChannelEvent} documentation to find out what a upstream
+ * event and a downstream event are and what fundamental differences they have,
+ * if you didn't read yet.
+ *
+ * <h3>{@link SimpleChannelHandler}</h3>
  * <p>
  * In most cases, you will get to use a {@link SimpleChannelHandler} to
  * implement a upstream handler because it provides an individual handler
@@ -132,19 +138,21 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
  *
  * <pre>
  * // Sending the event forward (upstream)
- * void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ * void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
  *     ...
  *     ctx.sendUpstream(e);
  *     ...
  * }
  *
  * // Sending the event backward (downstream)
- * void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
  *     ...
  *     ctx.sendDownstream(new MessageEvent(...));
  *     ...
  * }
  * </pre>
+ *
+ * <h4>Using the helper class to fire an event</h4>
  * <p>
  * You will also find various helper methods in {@link Channels} to be useful
  * to generate and fire an artificial or manipulated event.
diff --git a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java
index d89d1ca6b7..e81aabbf43 100644
--- a/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java
+++ b/src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java
@@ -44,8 +44,7 @@ import org.jboss.netty.logging.InternalLoggerFactory;
  * </p>
  * <pre>public class MyChannelHandler extends SimpleChannelHandler {
  *
- *     public void handleUpstream(
- *             ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
+ *     public void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
  *
  *         // Log all channel state changes.
  *         if (e instanceof ChannelStateEvent) {
diff --git a/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java b/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java
index bc2b9ccf58..70a6f28443 100644
--- a/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java
+++ b/src/main/java/org/jboss/netty/logging/InternalLoggerFactory.java
@@ -31,7 +31,7 @@ import org.jboss.netty.util.StackTraceSimplifier;
  * You can change it to your preferred logging framework before other Netty
  * classes are loaded:
  * <pre>
- * InternalLoggerFactory.setDefaultFactory(new Log4JLoggerFactory());
+ * InternalLoggerFactory.setDefaultFactory(new {@link Log4JLoggerFactory}());
  * </pre>
  * Please note that the new default factory is effective only for the classes
  * which were loaded after the default factory is changed.  Therefore,