issue #335 documentation improvements

monad/etc/monad.ucls

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<class-diagram version="1.1.9" icons="true" always-add-relationships="false" generalizations="true" realizations="true" 
+  associations="true" dependencies="false" nesting-relationships="true" router="FAN">  
+  <class id="1" language="java" name="com.iluwatar.monad.App" project="monad" 
+    file="/monad/src/main/java/com/iluwatar/monad/App.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="101" width="125" x="631" y="37"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <enumeration id="2" language="java" name="com.iluwatar.monad.Sex" project="monad" 
+    file="/monad/src/main/java/com/iluwatar/monad/Sex.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="119" width="137" x="424" y="286"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </enumeration>  
+  <class id="3" language="java" name="com.iluwatar.monad.User" project="monad" 
+    file="/monad/src/main/java/com/iluwatar/monad/User.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="209" width="167" x="424" y="37"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <class id="4" language="java" name="com.iluwatar.monad.Validator" project="monad" 
+    file="/monad/src/main/java/com/iluwatar/monad/Validator.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="191" width="343" x="41" y="37"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <association id="5">    
+    <end type="SOURCE" refId="3" navigable="false">      
+      <attribute id="6" name="sex"/>      
+      <multiplicity id="7" minimum="0" maximum="1"/>    
+    </end>    
+    <end type="TARGET" refId="2" navigable="true"/>    
+    <display labels="true" multiplicity="true"/>  
+  </association>  
+  <classifier-display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+    sort-features="false" accessors="true" visibility="true">    
+    <attributes public="true" package="true" protected="true" private="true" static="true"/>    
+    <operations public="true" package="true" protected="true" private="true" static="true"/>  
+  </classifier-display>  
+  <association-display labels="true" multiplicity="true"/>
+</class-diagram>

monad/index.md

@@ -3,17 +3,21 @@ layout: pattern
 title: Monad
 folder: monad
 permalink: /patterns/monad/
-categories: Presentation Tier
+categories: Other
 tags:
  - Java
  - Difficulty-Advanced
+ - Functional
 ---
 
 ## Intent
 
 Monad pattern based on monad from linear algebra represents the way of chaining operations
 together step by step. Binding functions can be described as passing one's output to another's input
-basing on the 'same type' contract.
+basing on the 'same type' contract. Formally, monad consists of a type constructor M and two
+operations:
+bind - that takes monadic object and a function from plain object to monadic value and returns monadic value
+return - that takse plain type object and returns this object wrapped in a monadic value.
 
 ![alt text](./etc/monad.png "Monad")
 
@@ -25,5 +29,7 @@ Use the Monad in any of the following situations
 * when you want to apply each function regardless of the result of any of them
 
 ## Credits
+
 * [Design Pattern Reloaded by Remi Forax](https://youtu.be/-k2X7guaArU)
 * [Brian Beckman: Don't fear the Monad](https://channel9.msdn.com/Shows/Going+Deep/Brian-Beckman-Dont-fear-the-Monads)
+* [Monad (functional programming) on Wikipedia] (https://en.wikipedia.org/wiki/Monad_(functional_programming)

monad/src/main/java/com/iluwatar/monad/User.java

@@ -8,11 +8,10 @@ public class User {
   private String email;
 
   /**
-   *
    * @param name  - name
    * @param age   - age
    * @param sex   - sex
-   * @param email - email
+   * @param email - email address
    */
   public User(String name, int age, Sex sex, String email) {
     this.name = name;

monad/src/main/java/com/iluwatar/monad/Validator.java

@@ -11,13 +11,22 @@ import java.util.function.Predicate;
  * given object together step by step. In Validator each step results in either success or
  * failure indicator, giving a way of receiving each of them easily and finally getting
  * validated object or list of exceptions.
+ *
  * @param <T> Placeholder for an object.
  */
 public class Validator<T> {
+  /**
+   * Object that is validated
+   */
   private final T t;
+
+  /**
+   * List of exception thrown during validation.
+   */
   private final List<Throwable> exceptions = new ArrayList<>();
 
   /**
+   * Creates a monadic value of given object.
    * @param t object to be validated
    */
   private Validator(T t) {
@@ -52,6 +61,7 @@ public class Validator<T> {
   /**
    * Extension for the {@link Validator#validate(Function, Predicate, String)} method,
    * dedicated for objects, that need to be projected before requested validation.
+   *
    * @param projection function that gets an objects, and returns projection representing
    *                   element to be validated.
    * @param validation see {@link Validator#validate(Function, Predicate, String)}
@@ -65,7 +75,7 @@ public class Validator<T> {
   }
 
   /**
-   * To receive validated object.
+   * Receives validated object or throws exception when invalid.
    *
    * @return object that was validated
    * @throws IllegalStateException when any validation step results with failure