Improved Flyweight example comments.

flyweight/src/main/java/com/iluwatar/AlchemistShop.java

@@ -5,7 +5,8 @@ import java.util.List;
 
 /**
  * 
- * The class that needs many objects.
+ * AlchemistShop holds potions on its shelves.
+ * It uses PotionFactory to provide the potions.
  * 
  */
 public class AlchemistShop {
@@ -52,6 +53,5 @@ public class AlchemistShop {
 		for (Potion p : bottomShelf) {
 			p.drink();
 		}
-
 	}
 }

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

@@ -2,9 +2,13 @@ package com.iluwatar;
 
 /**
  * 
- * Flyweight (PotionFactory) is useful when there is plethora of objects
- * (Potion). It provides means to decrease resource usage by sharing object
- * instances.
+ * Flyweight pattern is useful when the program needs a huge amount of objects.
+ * It provides means to decrease resource usage by sharing object instances.
+ * 
+ * In this example AlchemistShop has great amount of potions on its shelves.
+ * To fill the shelves AlchemistShop uses PotionFactory (which represents
+ * the Flyweight in this example). Internally PotionFactory holds a map
+ * of the potions and lazily creates new ones when requested.
  * 
  */
 public class App {

flyweight/src/main/java/com/iluwatar/Potion.java

@@ -2,7 +2,7 @@ package com.iluwatar;
 
 /**
  * 
- * Interface for objects.
+ * Interface for Potions.
  * 
  */
 public interface Potion {

flyweight/src/main/java/com/iluwatar/PotionFactory.java

@@ -4,7 +4,10 @@ import java.util.EnumMap;
 
 /**
  * 
- * Flyweight.
+ * PotionFactory is the Flyweight in this example.
+ * It minimizes memory use by sharing object instances.
+ * It holds a map of potion instances and new potions
+ * are created only when none of the type already exists.
  * 
  */
 public class PotionFactory {
@@ -45,5 +48,4 @@ public class PotionFactory {
 		}
 		return potion;
 	}
-
 }

flyweight/src/main/java/com/iluwatar/PotionType.java

@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Enumeration for potion types.
+ *
+ */
 public enum PotionType {
 
 	HEALING, INVISIBILITY, STRENGTH, HOLY_WATER, POISON;

flyweight/src/main/java/com/iluwatar/StrengthPotion.java

@@ -7,5 +7,4 @@ public class StrengthPotion implements Potion {
 		System.out.println("You feel strong. (Potion="
 				+ System.identityHashCode(this) + ")");
 	}
-
 }