Document the required order of &-parameters

NEWS.rst

@@ -41,6 +41,8 @@ Other Breaking Changes
 * `HySymbol` no longer inherits from `HyString`.
 * `(except)` is no longer allowed. Use `(except [])` instead.
 * `(import [foo])` is no longer allowed. Use `(import foo)` instead.
+* `&`-parameters in lambda lists must now appear in the same order that
+  Python expects.
 
 New Features
 ------------------------------

docs/language/api.rst

@@ -457,7 +457,11 @@ and the *body* of the function:
 
     (defn name [params] body)
 
-Parameters may have the following keywords in front of them:
+Parameters may be prefixed with the following special symbols. If you use more
+than one, they can only appear in the given order (so all `&optional`
+parameters must precede any `&rest` parameter, `&rest` must precede `&kwonly`,
+and `&kwonly` must precede `&kwargs`). This is the same order that Python
+requires.
 
 &optional
     Parameter is optional. The parameter can be given as a two item list, where
@@ -476,26 +480,6 @@ Parameters may have the following keywords in front of them:
         => (total-value 100 1)
         101.0
 
-&kwargs
-    Parameter will contain 0 or more keyword arguments.
-
-    The following code examples defines a function that will print all keyword
-    arguments and their values.
-
-    .. code-block:: clj
-
-        => (defn print-parameters [&kwargs kwargs]
-        ...    (for [(, k v) (.items kwargs)] (print k v)))
-
-        => (print-parameters :parameter-1 1 :parameter-2 2)
-        parameter_1 1
-        parameter_2 2
-
-        ; to avoid the mangling of '-' to '_', use unpacking:
-        => (print-parameters #** {"parameter-1" 1 "parameter-2" 2})
-        parameter-1 1
-        parameter-2 2
-
 &rest
     Parameter will contain 0 or more positional arguments. No other positional
     arguments may be specified after this one.
@@ -517,7 +501,7 @@ Parameters may have the following keywords in front of them:
         8
         => (zig-zag-sum 1 2 3 4 5 6)
         -3
-
+		
 &kwonly
     .. versionadded:: 0.12.0
 
@@ -553,6 +537,25 @@ Parameters may have the following keywords in front of them:
 
     Availability: Python 3.
 
+&kwargs
+    Parameter will contain 0 or more keyword arguments.
+
+    The following code examples defines a function that will print all keyword
+    arguments and their values.
+
+    .. code-block:: clj
+
+        => (defn print-parameters [&kwargs kwargs]
+        ...    (for [(, k v) (.items kwargs)] (print k v)))
+
+        => (print-parameters :parameter-1 1 :parameter-2 2)
+        parameter_1 1
+        parameter_2 2
+
+        ; to avoid the mangling of '-' to '_', use unpacking:
+        => (print-parameters #** {"parameter-1" 1 "parameter-2" 2})
+        parameter-1 1
+        parameter-2 2
 
 defn/a
 ------