Added comments and class diagram.

specification/src/main/java/com/iluwatar/app/App.java

@@ -16,7 +16,21 @@ import com.iluwatar.property.Movement;
 import com.iluwatar.selector.ColorSelector;
 import com.iluwatar.selector.MovementSelector;
 
+/**
+ * 
+ * The central idea of Specification pattern is to separate the statement of how to match a candidate, from the
+ * candidate object that it is matched against. As well as its usefulness in selection, it is also valuable for
+ * validation and for building to order.
+ * 
+ * In this example we have a pool of creatures with different properties. We then have defined separate selection
+ * rules (Specifications) that we apply to the collection and as output receive only the creatures that match
+ * the selection criteria.
+ * 
+ * http://martinfowler.com/apsupp/spec.pdf
+ *
+ */
 public class App {
+	
     public static void main( String[] args ) {
     	// initialize creatures list
     	List<Creature> creatures = Arrays.asList(new Goblin(), new Octopus(), new Dragon(), new Shark(), new Troll(), new KillerBee());

specification/src/main/java/com/iluwatar/creature/AbstractCreature.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Base class for concrete creatures.
+ *
+ */
 public abstract class AbstractCreature implements Creature {
 
 	private String name;

specification/src/main/java/com/iluwatar/creature/Creature.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Creature interface.
+ *
+ */
 public interface Creature {
 
 	String getName();

specification/src/main/java/com/iluwatar/creature/Dragon.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Dragon creature.
+ *
+ */
 public class Dragon extends AbstractCreature {
 
 	public Dragon() {

specification/src/main/java/com/iluwatar/creature/Goblin.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Goblin creature.
+ *
+ */
 public class Goblin extends AbstractCreature {
 
 	public Goblin() {

specification/src/main/java/com/iluwatar/creature/KillerBee.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * KillerBee creature.
+ *
+ */
 public class KillerBee extends AbstractCreature {
 
 	public KillerBee() {

specification/src/main/java/com/iluwatar/creature/Octopus.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Octopus creature.
+ *
+ */
 public class Octopus extends AbstractCreature {
 
 	public Octopus() {

specification/src/main/java/com/iluwatar/creature/Shark.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Shark creature.
+ *
+ */
 public class Shark extends AbstractCreature {
 
 	public Shark() {

specification/src/main/java/com/iluwatar/creature/Troll.java

@@ -4,6 +4,11 @@ import com.iluwatar.property.Color;
 import com.iluwatar.property.Movement;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Troll creature.
+ *
+ */
 public class Troll extends AbstractCreature {
 	
 	public Troll() {

specification/src/main/java/com/iluwatar/property/Color.java

@@ -1,5 +1,10 @@
 package com.iluwatar.property;
 
+/**
+ * 
+ * Color property.
+ *
+ */
 public enum Color {
 
     DARK("dark"), LIGHT("light"), GREEN("green"), RED("red");

specification/src/main/java/com/iluwatar/property/Movement.java

@@ -1,5 +1,10 @@
 package com.iluwatar.property;
 
+/**
+ * 
+ * Movement property.
+ *
+ */
 public enum Movement {
 
     WALKING("walking"), SWIMMING("swimming"), FLYING("flying");

specification/src/main/java/com/iluwatar/property/Size.java

@@ -2,7 +2,7 @@ package com.iluwatar.property;
 
 /**
  *
- * Enumeration for creature size.
+ * Size property.
  *
  */
 public enum Size {

specification/src/main/java/com/iluwatar/selector/ColorSelector.java

@@ -5,6 +5,11 @@ import java.util.function.Predicate;
 import com.iluwatar.creature.Creature;
 import com.iluwatar.property.Color;
 
+/**
+ * 
+ * Color selector.
+ *
+ */
 public class ColorSelector implements Predicate<Creature> {
 
 	private final Color c;

specification/src/main/java/com/iluwatar/selector/MovementSelector.java

@@ -5,6 +5,11 @@ import java.util.function.Predicate;
 import com.iluwatar.creature.Creature;
 import com.iluwatar.property.Movement;
 
+/**
+ * 
+ * Movement selector.
+ *
+ */
 public class MovementSelector implements Predicate<Creature> {
 	
 	private final Movement m;

specification/src/main/java/com/iluwatar/selector/SizeSelector.java

@@ -5,6 +5,11 @@ import java.util.function.Predicate;
 import com.iluwatar.creature.Creature;
 import com.iluwatar.property.Size;
 
+/**
+ * 
+ * Size selector.
+ *
+ */
 public class SizeSelector implements Predicate<Creature> {
 
 	private final Size s;