Update according to review comments #397

- Added descriptions
- Added junit tests
- Added javadoc
- Added index.md
- Added class diagrams

mutex/src/main/java/com/iluwatar/mutex/App.java

@@ -23,7 +23,15 @@
 package com.iluwatar.mutex;
 
 /**
- * App.
+ * A Mutex prevents multiple threads from accessing a resource simultaneously.
+ * <p>
+ * In this example we have two thieves who are taking beans from a jar.
+ * Only one thief can take a bean at a time. This is ensured by a Mutex lock
+ * which must be acquired in order to access the jar. Each thief attempts to
+ * acquire the lock, take a bean and then release the lock. If the lock has 
+ * already been acquired, the thief will be prevented from continuing (blocked)
+ * until the lock has been released. The thieves stop taking beans once there
+ * are no beans left to take.
  */
 public class App {
 

mutex/src/main/java/com/iluwatar/mutex/Jar.java

@@ -23,12 +23,20 @@
 package com.iluwatar.mutex;
 
 /**
- * Jar.
+ * A Jar has a resource of beans which can only be accessed by a single Thief
+ * (thread) at any one time. A Mutex lock is used to prevent more than one Thief
+ * taking a bean simultaneously. 
  */
 public class Jar {
 
-  private Lock lock;
+  /**
+   * The lock which must be acquired to access the beans resource.
+   */
+  private final Lock lock;
 
+  /**
+   * The resource within the jar.
+   */
   private int beans = 1000;
 
   public Jar(Lock lock) {
@@ -36,7 +44,7 @@ public class Jar {
   }
 
   /**
-   * takeBean method
+   * Method for a thief to take a bean.
    */
   public boolean takeBean(Thief thief) {
     boolean success = false;

mutex/src/main/java/com/iluwatar/mutex/Lock.java

@@ -23,7 +23,7 @@
 package com.iluwatar.mutex;
 
 /**
- * Lock.
+ * Lock is an interface for a lock which can be acquired and released.
  */
 public interface Lock {
 

mutex/src/main/java/com/iluwatar/mutex/Mutex.java

@@ -23,11 +23,20 @@
 package com.iluwatar.mutex;
 
 /**
- * Mutex.
+ * Mutex is an implementation of a mutual exclusion lock.
  */
 public class Mutex implements Lock {
-  private Object owner = null;
 
+  /**
+   * The current owner of the lock.
+   */
+  private Object owner;
+
+  /**
+   * Method called by a thread to acquire the lock. If the lock has already
+   * been acquired this will wait until the lock has been released to 
+   * re-attempt the acquire.
+   */
   @Override
   public synchronized void acquire() throws InterruptedException {
     while (owner != null) {
@@ -37,6 +46,9 @@ public class Mutex implements Lock {
     owner = Thread.currentThread();
   }
 
+  /**
+   * Method called by a thread to release the lock.
+   */
   @Override
   public synchronized void release() {
     owner = null;

mutex/src/main/java/com/iluwatar/mutex/Thief.java

@@ -23,19 +23,30 @@
 package com.iluwatar.mutex;
 
 /**
- * Thief.
+ * Thief is a class which continually tries to acquire a jar and take a bean
+ * from it. When the jar is empty the thief stops.
  */
 public class Thief extends Thread {
 
-  private String name;
-
-  private Jar jar;
+  /**
+   * The name of the thief. 
+   */
+  private final String name;
+  
+  /**
+   * The jar
+   */
+  private final Jar jar;
 
   public Thief(String name, Jar jar) {
     this.name = name;
     this.jar = jar;
   }
 
+  /**
+   * In the run method the thief repeatedly tries to take a bean until none
+   * are left.
+   */
   @Override
   public void run() {
     int beans = 0;