README.rdoc in rumonade-0.1.1 vs README.rdoc in rumonade-0.1.2

@@ -1,20 +1,24 @@
 = Rumonade[https://rubygems.org/gems/rumonade]
 
+Project: github[http://github.com/ms-ati/rumonade]
+
+Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/file/README.rdoc]
+
 == A Ruby[http://www.ruby-lang.org] Monad[http://en.wikipedia.org/wiki/Monad_(functional_programming)] Library, Inspired by Scala[http://www.scala-lang.org]
 
 Are you working in both the Scala[http://www.scala-lang.org] and Ruby[http://www.ruby-lang.org] worlds,
 and finding that you miss some of the practical benefits of Scala's
 monads[http://james-iry.blogspot.com/2007/09/monads-are-elephants-part-1.html] in Ruby?
 Then Rumonade is for you.
 
 The goal of this library is to make the most common and useful Scala monadic idioms available in Ruby via the following classes:
-* Rumonade::Option
-* Array
-* Either
-* Hash
-* (more TBD)
+* {Rumonade::Option Option}
+* {Rumonade::ArrayExtensions Array}
+* {Rumonade::Either Either}
+* Hash -- _coming_ _soon!_
+* (_more_ _TBD_)
 
 Syntactic support for scala-like for-comprehensions[http://www.scala-lang.org/node/111] will be implemented
 as a sequence of calls to #flat_map, #select, etc, modelling Scala's
 approach[http://stackoverflow.com/questions/3754089/scala-for-comprehension/3754568#3754568].
 
@@ -22,28 +26,32 @@
 idiom will be implemented to turn blocks which might throw exceptions into Option or Either
 results. If this proves useful (and a good fit for Ruby), then more narrow functional catchers can be implemented as well.
 
 == Usage
 
-You can transform possibly nil values in a functional fashion, which many find more clear and elegant:
+Using Option, one can transform _possibly_ _nil_ values in a _functional_ fashion, which can increase clarity while
+eliminating opportunities for bugs:
 
-  require 'date'
-  require 'time'
-  require 'rumonade'
-
   def format_date_in_march(time_or_date_or_nil)
-    Option(time_or_date_or_nil).
-        map(&:to_date).select {|d| d.month == 3}.
-        map(&:to_s).map {|s| s.gsub('-', '')}.get_or_else("not in march!")
+    Option(time_or_date_or_nil).      # wraps possibly-nil value in an Option monad (Some or None)
+        map(&:to_date).               # transforms a contained Time value into a Date value
+        select {|d| d.month == 3}.    # filters out non-matching Date values (Some becomes None)
+        map(&:to_s).                  # transforms a contained Date value into a String value
+        map {|s| s.gsub('-', '')}.    # transforms a contained String value by removing '-'
+        get_or_else("not in march!")  # returns the contained value, or the alternative if None
   end
 
   format_date_in_march(nil)                            # => "not in march!"
-  format_date_in_march(Time.parse('2011-01-01 12:34')) # => "not in march!"
+  format_date_in_march(Time.parse('2009-01-01 01:02')) # => "not in march!"
   format_date_in_march(Time.parse('2011-03-21 12:34')) # => "20110321"
 
-(more examples coming soon...)
+Note:
+* each step of the chained computations above are functionally isolated
+* the value can notionally _start_ as nil, or _become_ nil during a computation, without effecting any other chained computations
 
+(_more_ _examples_ _coming_ _soon_...)
+
 == Approach
 
 There have been many[http://moonbase.rydia.net/mental/writings/programming/monads-in-ruby/00introduction.html]
 posts[http://pretheory.wordpress.com/2008/02/14/the-maybe-monad-in-ruby/]
 and[http://www.valuedlessons.com/2008/01/monads-in-ruby-with-nice-syntax.html]
@@ -52,10 +60,10 @@
 
 Rumonade wants to be a practical drop-in Monad solution that will fit well into the Ruby world.
 
 The priorities for Rumonade are:
 1. Practical usability in day-to-day Ruby
-   * <b>don't</b> mess up normal idioms of the language (e.g., Array#map)
+   * <b>don't</b> mess up normal idioms of the language (e.g., Hash#map)
    * <b>don't</b> slow down normal idioms of the language (e.g., Array#map)
 2. Rubyish-ness of usage
    * Monad is a mix-in, requiring methods self.unit and #bind be implemented by target classes
    * Prefer blocks to lambda/Procs where possible
 3. Equivalent idioms to Scala where possible