From 4e61ae59fdf004660e416acad48207cc0251e2c5 Mon Sep 17 00:00:00 2001
From: "Paul R. Tagliamonte" <paultag@debian.org>
Date: Mon, 8 Apr 2013 21:53:06 -0400
Subject: [PATCH] small internals tweak

---
 docs/language/api.rst | 54 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/docs/language/api.rst b/docs/language/api.rst
index b29d849..a59a450 100644
--- a/docs/language/api.rst
+++ b/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.