Document defn/a, fn/a, for/a, with/a

docs/language/api.rst

@@ -729,6 +729,17 @@ Parameters may have the following keywords in front of them:
     Availability: Python 3.
 
 
+defn/a
+------
+
+``defn/a`` macro is a variant of ``defn`` that instead defines
+coroutines. It takes three parameters: the *name* of the function to
+define, a vector of *parameters*, and the *body* of the function:
+
+.. code-block:: clj
+
+    (defn/a name [params] body)
+
 defmain
 -------
 
@@ -1035,6 +1046,24 @@ not execute.
     loop finished
 
 
+for/a
+-----
+
+``for/a`` behaves like ``for`` but is used to call a function for each
+element generated by an asyncronous generator expression. The results
+of each call are discarded and the ``for/a`` expression returns
+``None`` instead.
+
+.. code-block:: clj
+
+    ;; assuming that (side-effect) is a function that takes a single parameter
+    (for/a [element (agen)] (side-effect element))
+
+    ;; for/a can have an optional else block
+    (for/a [element (agen)] (side-effect element)
+         (else (side-effect-2)))
+
+
 genexpr
 -------
 
@@ -1298,6 +1327,14 @@ This can be confirmed via Python's built-in ``help`` function::
     Multiplies input by three and returns result
     (END)
 
+fn/a
+----
+
+``fn/a`` is a variant of ``fn`` than defines an anonymous coroutine.
+The parameters are similar to ``defn/a``: the first parameter is
+vector of parameters and the rest is the body of the function. ``fn/a`` returns a
+new coroutine.
+
 last
 -----------
 
@@ -1868,6 +1905,26 @@ case it returns ``None``. So, the previous example could also be written
 
     (print (with [f (open "NEWS")] (.read f)))
 
+with/a
+------
+
+``with/a`` behaves like ``with``, but is used to wrap the execution of
+a block within a asynchronous context manager. The context manager can
+then set up the local system and tear it down in a controlled manner
+asynchronously.
+
+.. code-block:: clj
+
+    (with/a [arg (expr)] block)
+
+    (with/a [(expr)] block)
+
+    (with/a [arg (expr) (expr)] block)
+
+``with/a`` returns the value of its last form, unless it suppresses an exception
+(because the context manager's ``__aexit__`` method returned true), in which
+case it returns ``None``.
+
 with-decorator
 --------------