From b3a85801bd63f1402d119a7186506ab4e85e7cdf Mon Sep 17 00:00:00 2001
From: Tim Martin <tim@asymptotic.co.uk>
Date: Tue, 26 Jan 2016 20:27:07 +0000
Subject: [PATCH] Documentation of the &key modifier in (defn)

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

diff --git a/docs/language/api.rst b/docs/language/api.rst
index 13760fa..c96e0b6 100644
--- a/docs/language/api.rst
+++ b/docs/language/api.rst
@@ -400,7 +400,7 @@ below:
 .. _defn:
 
 defn
-------------
+----
 
 ``defn`` macro is used to define functions. It takes three
 parameters: the *name* of the function to define, a vector of *parameters*,
@@ -430,7 +430,26 @@ Parameters may have the following keywords in front of them:
 	101.0
 
 &key
+    Parameter is a dict of keyword arguments. The keys of the dict
+    specify the parameter names and the values give the default values
+    of the parameters.
 
+    .. code-block:: clj
+
+       => (defn key-parameters [&key {"a" 1 "b" 2}]
+       ... (print "a is" a "and b is" b))
+       => (key-parameters :a 1 :b 2)
+       a is 1 and b is 2
+       => (key-parameters :b 1 :a 2)
+       a is 2 and b is 1
+
+    The following declarations are equivalent:
+
+    .. code-block:: clj
+
+       (defn key-parameters [&key {"a" 1 "b" 2}])
+
+       (defn key-parameters [&optional [a 1] [b 2]])
 
 &kwargs
     Parameter will contain 0 or more keyword arguments.