Merge branch 'master' into feature/quoting

docs/language/api.rst

@@ -45,3 +45,57 @@ the `do` or `progn` forms can be used in full code branches. What that means
 is basically `(do)` and `(progn)` can only be used where a Python expression
 can be used. These forms don't actually allow you to break Pythonic internals
 such as `lambda` or `list-comp`, where you can only have one expression.
+
+
+Some example usage
+
+.. code-block:: clj
+
+    (if true
+      (do (print "Side effects rock!")
+          (print "Yeah, really!")))
+
+`do` can accept any number of arguments, from 1 to n.
+
+
+throw / raise
+-------------
+
+the `throw` or `raise` forms can be used to raise an Exception at runtime.
+
+
+Example usage
+
+.. code-block:: clj
+
+    (throw)
+    ; re-rase the last exception
+    
+    (throw IOError)
+    ; Throw an IOError
+    
+    (throw (IOError "foobar"))
+    ; Throw an IOError("foobar")
+
+
+`throw` can acccept a single argument (an `Exception` class or instance), or
+no arguments to re-raise the last Exception.
+
+
+try
+---
+
+.. TODO::
+    Document the else / finally syntax.
+
+the `try` form is used to start a `try` / `catch` block. The form is used
+as follows
+
+.. code-block:: clj
+
+    (try
+        (error-prone-function)
+        (catch [e SomeException] (err "It sucks!")))
+
+`try` must contain at least one `catch` block, and may optionally have an
+`else` or `finally` block.