Update readme.

1 files changed, 45 insertions, 6 deletions

diff --git a/README.md b/README.md
index 58c8f80..dde38cc 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,49 @@
 Scheme Monads
 =============
 
-These are a proof of concept of Haskell style monads in scheme.
-They currently support both bind (`>>=`) and `do` notation.
+In an attempt to understand how Monads in Haskell actually works I set out to
+reimplement them myself in scheme.
 
-TODO
-----
-- A propper way to call `return`. Probably by allowing bind to act as a macro
-  and introduce a return procedure of the appropriate type.
\ No newline at end of file
+Examples
+--------
+
+	(use-modules (monad)
+				 (monad state))
+
+	(run-state (do x <- (<$> sqrt (get))
+				   let y = (+ x 10)
+				   (put y)
+				   (return-state x))
+			   64)
+	;; => (8 18)
+
+	(>> (just 1)
+		(just 2))
+	;; => [Just 2]
+
+Unfortunately, it doesn't really short circuit as one would have hoped:
+
+	(>> (nothing) (just (/ 1 0)))
+	<unnamed port>:1520:36: Throw to key `numerical-overflow' with args `("/"
+	"Numerical overflow" #f #f)'.
+
+
+
+Usage
+-----
+The module `(monad)` contains all base bindings, allowing usage of the monad
+system. The modules `(monad *)` contains different data types, including
+optional, stacks, and more.
+
+Documentation
+-------------
+Documentation can be build with
+
+	make doc
+
+It however doesn't work to well, since the `(texinfo reflection)` modules is
+less than perfect.
+
+Tests & Examples
+----------------
+`tests/test.scm` contains a few tests and examples of how to use the code.