Finish javadocs for common module

common/src/main/java/io/netty/util/Attribute.java

@@ -15,11 +15,42 @@
  */
 package io.netty.util;
 
+/**
+ * An attribute which allows to store an value reference. It may be updated atomically and so is thread-safe.
+ *
+ * @param <T>   the type of the value it holds.
+ */
 public interface Attribute<T> {
+    /**
+     * Returns the current value, which may be {@code null}
+     */
     T get();
+
+    /**
+     * Sets the value
+     */
     void set(T value);
+
+    /**
+     *  Atomically sets to the given value and returns the old value which may be {@code null} if non was set before.
+     */
     T getAndSet(T value);
+
+    /**
+     *  Atomically sets to the given value if this {@link Attribute} does not contain a value at the moment.
+     *  If it was not possible to set the value as it contains a value it will just return the current value.
+     */
     T setIfAbsent(T value);
+
+    /**
+     * Atomically sets the value to the given updated value if the current value == the expected value.
+     * If it the set was successful it returns {@code true} otherwise {@code false}.
+     */
     boolean compareAndSet(T oldValue, T newValue);
+
+    /**
+     * Remove the current value which is stored in this {@link Attribute}, which means after this call {@link #get()}
+     * will return {@code null}.
+     */
     void remove();
 }

common/src/main/java/io/netty/util/AttributeKey.java

@@ -18,10 +18,22 @@ package io.netty.util;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+/**
+ * Key which can be used to access {@link Attribute} out of the {@link AttributeMap}. Be aware that it is not be
+ * possible to have multiple keys with the same name.
+ *
+ *
+ * @param <T>   the type of the {@link Attribute} which can be accessed via this {@link AttributeKey}.
+ */
 public final class AttributeKey<T> extends UniqueName {
 
     private static final ConcurrentMap<String, Boolean> names = new ConcurrentHashMap<String, Boolean>();
 
+    /**
+     * Create a new instance
+     *
+     * @param name  the name under which the {@link AttributeKey} will be registered
+     */
     public AttributeKey(String name) {
         super(names, name);
     }

common/src/main/java/io/netty/util/AttributeMap.java

@@ -15,6 +15,15 @@
  */
 package io.netty.util;
 
+/**
+ * Holds {@link Attribute}s which can be accessed via {@link AttributeKey}.
+ *
+ * Implementations must be Thread-safe.
+ */
 public interface AttributeMap {
+    /**
+     * Get the {@link Attribute} for the given {@link AttributeKey}. This method will never return null, but may return
+     * an {@link AttributeKey} which has not value set yet.
+     */
     <T> Attribute<T> attr(AttributeKey<T> key);
 }

common/src/main/java/io/netty/util/DefaultAttributeMap.java

@@ -19,6 +19,10 @@ import java.util.IdentityHashMap;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 
+/**
+ * Default {@link AttributeMap} implementation which use simple synchronization to keep the memory overhead
+ * as low as possible.
+ */
 public class DefaultAttributeMap implements AttributeMap {
 
     // Initialize lazily to reduce memory consumption.
@@ -41,7 +45,7 @@ public class DefaultAttributeMap implements AttributeMap {
         return attr;
     }
 
-    private class DefaultAttribute<T> extends AtomicReference<T> implements Attribute<T> {
+    private static final class DefaultAttribute<T> extends AtomicReference<T> implements Attribute<T> {
 
         private static final long serialVersionUID = -2661411462200283011L;
 

common/src/main/java/io/netty/util/UniqueName.java

@@ -60,6 +60,7 @@ public class UniqueName implements Comparable<UniqueName> {
      *
      * @param args arguments to validate
      */
+    @SuppressWarnings("unused")
     protected void validateArgs(Object... args) {
         // Subclasses will override.
     }

common/src/main/java/io/netty/util/internal/DetectionUtil.java

@@ -118,14 +118,24 @@ public final class DetectionUtil {
         return IS_ROOT;
     }
 
+    /**
+     * Return {@code true} if {@link sun.misc.Unsafe} was found on the classpath and can be used.
+     */
     public static boolean hasUnsafe() {
         return HAS_UNSAFE;
     }
 
+    /**
+     * Return the version of Java under which this library is used.
+     */
     public static int javaVersion() {
         return JAVA_VERSION;
     }
 
+    /**
+     * Return {@code true} if direct buffers can be freed using an optimized way and so memory footprint will be very
+     * small.
+     */
     public static boolean canFreeDirectBuffer() {
         return CAN_FREE_DIRECT_BUFFER;
     }

common/src/main/java/io/netty/util/internal/SharedResourceMisuseDetector.java

@@ -24,7 +24,7 @@ import java.util.concurrent.atomic.AtomicLong;
 /**
  * Warn when user creates too many instances to avoid {@link OutOfMemoryError}.
  */
-public class SharedResourceMisuseDetector {
+public final class SharedResourceMisuseDetector {
 
     private static final int MAX_ACTIVE_INSTANCES = 256;
     private static final InternalLogger logger =
@@ -41,6 +41,9 @@ public class SharedResourceMisuseDetector {
         this.type = type;
     }
 
+    /**
+     * Increase the use-count of the instance
+     */
     public void increase() {
         if (activeInstances.incrementAndGet() > MAX_ACTIVE_INSTANCES) {
             if (logger.isWarnEnabled()) {
@@ -55,6 +58,9 @@ public class SharedResourceMisuseDetector {
         }
     }
 
+    /**
+     * Decrease the use-count of the instance
+     */
     public void decrease() {
         activeInstances.decrementAndGet();
     }

common/src/main/java/io/netty/util/internal/Signal.java

@@ -21,6 +21,11 @@ import io.netty.util.UniqueName;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+/**
+ * A special {@link Error} which is used to signal some state via an {@link Error}.
+ *
+ * This instance will have no stacktrace filled or any cause set to safe the overhead.
+ */
 public final class Signal extends Error {
 
     private static final long serialVersionUID = -221145131122459977L;
@@ -30,11 +35,20 @@ public final class Signal extends Error {
 
     private final UniqueName uname;
 
+    /**
+     * Create a new instance
+     *
+     * @param name      the name under which it is registered
+     */
     public Signal(String name) {
         super(name);
         uname = new UniqueName(map, name);
     }
 
+    /**
+     * Check if the given {@link Signal} is the same as this instance. If not an {@link IllegalStateException} will
+     * be thrown.
+     */
     public void expect(Signal signal) {
         if (this != signal) {
             throw new IllegalStateException("unexpected signal: " + signal);