From 1d1d7b2a951ea043c5533bd4200d70205e8e03fd Mon Sep 17 00:00:00 2001
From: Cruz Julian Bishop <cruz@massive-dynamics.biz>
Date: Thu, 28 Jun 2012 16:37:41 +1000
Subject: [PATCH] Add documentation to NonReentrantLock

---
 .../netty/util/internal/NonReentrantLock.java | 62 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/common/src/main/java/io/netty/util/internal/NonReentrantLock.java b/common/src/main/java/io/netty/util/internal/NonReentrantLock.java
index e774796706..32f32fa5b9 100644
--- a/common/src/main/java/io/netty/util/internal/NonReentrantLock.java
+++ b/common/src/main/java/io/netty/util/internal/NonReentrantLock.java
@@ -20,48 +20,97 @@ import java.util.concurrent.locks.AbstractQueuedSynchronizer;
 import java.util.concurrent.locks.Condition;
 import java.util.concurrent.locks.Lock;
 
+/**
+ * A custom implementation of a lock that does not allow reentry
+ */
 public final class NonReentrantLock extends AbstractQueuedSynchronizer
-                             implements Lock {
+        implements Lock {
 
+    /**
+     * The serial version unique ID
+     */
     private static final long serialVersionUID = -833780837233068610L;
 
+    /**
+     * The {@link Thread} that owns this {@link NonReentrantLock}
+     */
     private Thread owner;
 
+    /**
+     * Locks this {@link NonReentrantLock}
+     */
     @Override
     public void lock() {
         acquire(1);
     }
 
+    /**
+     * Locks this {@link NonReentrantLock}, but allow interruption
+     *
+     * @throws InterruptedException The lock was interrupted
+     */
     @Override
     public void lockInterruptibly() throws InterruptedException {
         acquireInterruptibly(1);
     }
 
+    /**
+     * Try to lock this {@link NonReentrantLock}
+     *
+     * @return True if locking was successful, otherwise false
+     */
     @Override
     public boolean tryLock() {
         return tryAcquire(1);
     }
 
+    /**
+     * Tries to lock this {@link NonReentrantLock} over a period of time
+     *
+     * @param time The maximum number of time units to attempt to get a lock for.
+     * @param unit The {@link TimeUnit} associated with the time parameter
+     * @return True if the lock was successful, otherwise false
+     * @throws InterruptedException The locking attempt was interrupted
+     */
     @Override
     public boolean tryLock(long time, TimeUnit unit)
             throws InterruptedException {
         return tryAcquireNanos(1, unit.toNanos(time));
     }
 
+    /**
+     * Unlocks this {@link NonReentrantLock}
+     */
     @Override
     public void unlock() {
         release(1);
     }
 
+    /**
+     * Checks to see if this {@link NonReentrantLock} is held by the current {@link Thread}
+     *
+     * @return True if held by the current thread, otherwise false
+     */
     public boolean isHeldByCurrentThread() {
         return isHeldExclusively();
     }
 
+    /**
+     * Creates a new {@link Condition}
+     *
+     * @return The condition object
+     */
     @Override
     public Condition newCondition() {
         return new ConditionObject();
     }
 
+    /**
+     * Try to acquire a lock
+     *
+     * @param acquires A number that is sent by acquiring methods
+     * @return True if a lock is acquired, otherwise false
+     */
     @Override
     protected boolean tryAcquire(int acquires) {
         if (compareAndSetState(0, 1)) {
@@ -71,6 +120,12 @@ public final class NonReentrantLock extends AbstractQueuedSynchronizer
         return false;
     }
 
+    /**
+     * Tries to release the lock
+     *
+     * @param releases A number that is passed by the release methods
+     * @return True if a release is granted, otherwise false
+     */
     @Override
     protected boolean tryRelease(int releases) {
         if (Thread.currentThread() != owner) {
@@ -81,6 +136,11 @@ public final class NonReentrantLock extends AbstractQueuedSynchronizer
         return true;
     }
 
+    /**
+     * Checks to see if this {@link NonReentrantLock} is held exclusively by the current {@link Thread}
+     *
+     * @return True if held exclusively, otherwise false
+     */
     @Override
     protected boolean isHeldExclusively() {
         return getState() != 0 && owner == Thread.currentThread();