Merge pull request #1020 from timmartin/documentation

Documentation of the &key modifier in (defn)

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.