From f34a0182184d3b3cb046064c0dd32196182c31ad Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Sun, 10 Aug 2008 15:34:17 +0000
Subject: [PATCH] More JavaDoc

---
 .../java/org/jboss/netty/util/ImmediateExecutor.java |  3 +++
 src/main/java/org/jboss/netty/util/MapBackedSet.java |  7 +++++++
 .../org/jboss/netty/util/NamePreservingRunnable.java | 12 +++++++++---
 .../org/jboss/netty/util/SwitchableInputStream.java  |  8 ++++++++
 .../org/jboss/netty/util/TimeBasedUuidGenerator.java |  9 ++++++++-
 5 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/src/main/java/org/jboss/netty/util/ImmediateExecutor.java b/src/main/java/org/jboss/netty/util/ImmediateExecutor.java
index 8bbcca797f..7f1c6f3ff4 100644
--- a/src/main/java/org/jboss/netty/util/ImmediateExecutor.java
+++ b/src/main/java/org/jboss/netty/util/ImmediateExecutor.java
@@ -35,6 +35,9 @@ import java.util.concurrent.Executor;
  */
 public class ImmediateExecutor implements Executor {
 
+    /**
+     * The default instance.
+     */
     public static final ImmediateExecutor INSTANCE = new ImmediateExecutor();
 
     public void execute(Runnable command) {
diff --git a/src/main/java/org/jboss/netty/util/MapBackedSet.java b/src/main/java/org/jboss/netty/util/MapBackedSet.java
index 2b0306bb3d..4f26825164 100644
--- a/src/main/java/org/jboss/netty/util/MapBackedSet.java
+++ b/src/main/java/org/jboss/netty/util/MapBackedSet.java
@@ -43,10 +43,17 @@ public class MapBackedSet<E> extends AbstractSet<E> implements Serializable {
 
     private final Map<E, Boolean> map;
 
+    /**
+     * Creates a new instance which wraps the specified {@code map}.
+     */
     public MapBackedSet(Map<E, Boolean> map) {
         this.map = map;
     }
 
+    /**
+     * Creates a new instance which wraps the specified {@code map} and
+     * adds all elements of the specified collection.
+     */
     public MapBackedSet(Map<E, Boolean> map, Collection<E> c) {
         this.map = map;
         addAll(c);
diff --git a/src/main/java/org/jboss/netty/util/NamePreservingRunnable.java b/src/main/java/org/jboss/netty/util/NamePreservingRunnable.java
index 86134ff317..e094b1b5e4 100644
--- a/src/main/java/org/jboss/netty/util/NamePreservingRunnable.java
+++ b/src/main/java/org/jboss/netty/util/NamePreservingRunnable.java
@@ -26,7 +26,7 @@ import org.jboss.netty.logging.InternalLogger;
 import org.jboss.netty.logging.InternalLoggerFactory;
 
 /**
- * {@link Runnable} that changes the current thread name and reverts it back
+ * Meta {@link Runnable} that changes the current thread name and reverts it back
  * when its execution ends.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
@@ -42,6 +42,11 @@ public class NamePreservingRunnable implements Runnable {
     private final String newName;
     private final Runnable runnable;
 
+    /**
+     * Creates a new instance which wraps the specified {@code runnable}
+     * and changes the thread name to the specified thread name when the
+     * specified {@code runnable} is running.
+     */
     public NamePreservingRunnable(Runnable runnable, String newName) {
         this.runnable = runnable;
         this.newName = newName;
@@ -63,8 +68,9 @@ public class NamePreservingRunnable implements Runnable {
     }
 
     /**
-     * Wraps {@link Thread#setName(String)} to catch a possible {@link Exception}s such as
-     * {@link SecurityException} in sandbox environments, such as applets
+     * Wraps {@link Thread#setName(String)} to catch a possible
+     * {@link Exception} such as a {@link SecurityException} in a sandbox
+     * environment, such as an applet
      */
     private void setName(Thread thread, String name) {
         try {
diff --git a/src/main/java/org/jboss/netty/util/SwitchableInputStream.java b/src/main/java/org/jboss/netty/util/SwitchableInputStream.java
index d8ada3ca03..06094144ce 100644
--- a/src/main/java/org/jboss/netty/util/SwitchableInputStream.java
+++ b/src/main/java/org/jboss/netty/util/SwitchableInputStream.java
@@ -37,10 +37,18 @@ import java.io.InputStream;
  */
 public class SwitchableInputStream extends FilterInputStream {
 
+    /**
+     * Creates a new instance without initializing the reference to the
+     * underlying stream.
+     */
     public SwitchableInputStream() {
         super(null);
     }
 
+    /**
+     * Creates a new instance with the initial reference to the underlying
+     * stream.
+     */
     public void switchStream(InputStream in) {
         this.in = in;
     }
diff --git a/src/main/java/org/jboss/netty/util/TimeBasedUuidGenerator.java b/src/main/java/org/jboss/netty/util/TimeBasedUuidGenerator.java
index 87d9e1dac1..3301623e29 100644
--- a/src/main/java/org/jboss/netty/util/TimeBasedUuidGenerator.java
+++ b/src/main/java/org/jboss/netty/util/TimeBasedUuidGenerator.java
@@ -32,7 +32,11 @@ import java.util.UUID;
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * Generates a time-based {@link UUID}.
+ * Generates a time-based {@link UUID}.  Please note that this generator
+ * uses a pseudo HMAC which is generated based on various VM properties.
+ * Therefore, the pseudo HMAC can change for each VM instance even if you
+ * launch the VM in the same machine.  Its purpose is to generate a unique
+ * ID for one VM at most.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -123,6 +127,9 @@ public class TimeBasedUuidGenerator {
         }
     }
 
+    /**
+     * Returns a new time-based {@link UUID}.
+     */
     public static UUID generate() {
         long time = System.currentTimeMillis();
         int clockSeq = TimeBasedUuidGenerator.SEQUENCE.getAndIncrement();