Update according to review comments #397

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

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

@@ -23,7 +23,14 @@
 package com.iluwatar.semaphore;
 
 /**
- * App.
+ * A Semaphore mediates access by a group of threads to a pool of resources.
+ * <p>
+ * In this example a group of customers are taking fruit from a fruit shop.
+ * There is a bowl each of apples, oranges and lemons. Only one customer can 
+ * access a bowl simultaneously. A Semaphore is used to indicate how many 
+ * resources are currently available and must be acquired in order for a bowl 
+ * to be given to a customer. Customers continually try to take fruit until 
+ * there is no fruit left in the shop. 
  */
 public class App {
     

semaphore/src/main/java/com/iluwatar/semaphore/Customer.java

@@ -23,13 +23,25 @@
 package com.iluwatar.semaphore;
 
 /**
- * Customer.
+ * A Customer attempts to repeatedly take Fruit from the FruitShop by
+ * taking Fruit from FruitBowl instances.
  */
 public class Customer extends Thread {
-    
-  private String name;
-  private FruitShop fruitShop;
-  private FruitBowl fruitBowl;
+
+  /**
+   * Name of the Customer.
+   */
+  private final String name;
+  
+  /**
+   * The FruitShop he is using.
+   */
+  private final FruitShop fruitShop;
+  
+  /**
+   * Their bowl of Fruit.
+   */
+  private final FruitBowl fruitBowl;
   
   /**
    * Customer constructor
@@ -41,7 +53,8 @@ public class Customer extends Thread {
   }
   
   /**
-   * run method
+   * The Customer repeatedly takes Fruit from the FruitShop until no Fruit
+   * remains.
    */   
   public void run() {
         

semaphore/src/main/java/com/iluwatar/semaphore/Fruit.java

@@ -23,7 +23,7 @@
 package com.iluwatar.semaphore;
 
 /**
- * Fruit.
+ * Fruit is a resource stored in a FruitBowl. 
  */
 public class Fruit {
 

semaphore/src/main/java/com/iluwatar/semaphore/FruitBowl.java

@@ -25,23 +25,33 @@ package com.iluwatar.semaphore;
 import java.util.ArrayList;
 
 /**
- * FruitBowl.
+ * A FruitBowl contains Fruit. 
  */
 public class FruitBowl {
     
   private ArrayList<Fruit> fruit = new ArrayList<>();
 
+  /**
+   * 
+   * @return The amount of Fruit left in the bowl. 
+   */
   public int countFruit() {
     return fruit.size();
   }
 
+  /**
+   * Put an item of Fruit into the bowl.
+   * 
+   * @param f fruit
+   */
   public void put(Fruit f) {
     fruit.add(f);
   }
   
   /**
-   * take method
-   */   
+   * Take an item of Fruit out of the bowl.
+   * @return The Fruit taken out of the bowl, or null if empty.
+   */
   public Fruit take() {
     if (fruit.isEmpty()) {
       return null;

semaphore/src/main/java/com/iluwatar/semaphore/FruitShop.java

@@ -23,22 +23,31 @@
 package com.iluwatar.semaphore;
 
 /**
- * FruitShop.
+ * A FruitShop contains three FruitBowl instances and controls access to them.
  */
 public class FruitShop {
-    
+   
+  /**
+   * The FruitBowl instances stored in the class.
+   */
   private FruitBowl[] bowls = {
     new FruitBowl(),
     new FruitBowl(),
     new FruitBowl()
   };
-    
+
+  /**
+   * Access flags for each of the FruitBowl instances.
+   */
   private boolean[] available = {
     true,
     true,
     true
   };
-    
+
+  /**
+   * The Semaphore that controls access to the class resources.
+   */
   private Semaphore semaphore;
   
   /**
@@ -53,13 +62,19 @@ public class FruitShop {
         
     semaphore = new Semaphore(3);
   }
-    
+
+  /**
+   * 
+   * @return The amount of Fruit left in the shop.
+   */
   public synchronized int countFruit() {
     return bowls[0].countFruit() + bowls[1].countFruit() + bowls[2].countFruit();
   }
   
   /**
-   * takeBowl method
+   * Method called by Customer to get a FruitBowl from the shop. This method
+   * will try to acquire the Semaphore before returning the first available 
+   * FruitBowl.
    */   
   public synchronized FruitBowl takeBowl() {
         
@@ -88,7 +103,9 @@ public class FruitShop {
   }
   
   /**
-   * returnBowl method
+   * Method called by a Customer instance to return a FruitBowl to the shop. 
+   * This method releases the Semaphore, making the FruitBowl available to 
+   * another Customer.
    */   
   public synchronized void returnBowl(FruitBowl bowl) {
     if (bowl == bowls[0]) {

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

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

semaphore/src/main/java/com/iluwatar/semaphore/Semaphore.java

@@ -23,10 +23,13 @@
 package com.iluwatar.semaphore;
 
 /**
- * Semaphore.
+ * Semaphore is an implementation of a semaphore lock.
  */
 public class Semaphore implements Lock {
 
+  /**
+   * The number of concurrent resource accesses which are allowed.
+   */
   private int counter;
     
   public Semaphore(int counter) {
@@ -34,7 +37,9 @@ public class Semaphore implements Lock {
   }
   
   /**
-   * acquire method
+   * Method called by a thread to acquire the lock. If there are no resources
+   * available this will wait until the lock has been released to re-attempt
+   * the acquire.
    */
   public synchronized void acquire() throws InterruptedException {
     while (counter == 0) {
@@ -43,6 +48,9 @@ public class Semaphore implements Lock {
     counter = counter - 1;
   }
   
+  /**
+   * Method called by a thread to release the lock.
+   */
   public synchronized void release() {
     counter = counter + 1;
     notify();