Merge pull request #1659 from Kodiologist/doc-updates

Small documentation additions

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

@@ -449,15 +449,22 @@ below:
 defn
 ----
 
-``defn`` macro is used to define functions. It takes three
-parameters: the *name* of the function to define, a vector of *parameters*,
-and the *body* of the function:
+``defn`` is used to define functions. It requires two arguments: a name (given
+as a symbol) and a list of parameters (also given as symbols). Any remaining
+arguments constitute the body of the function.
 
 .. code-block:: clj
 
-    (defn name [params] body)
+    (defn name [params] bodyform1 bodyform2...)
 
-Parameters may have the following keywords in front of them:
+If there at least two body forms, and the first of them is a string literal,
+this string becomes the :ref:`docstring <py:docstring>` of the function.
+
+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 +483,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 +504,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 +540,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
 ------

docs/language/syntax.rst

@@ -67,6 +67,8 @@ of bytes. So when running under Python 3, Hy translates ``"foo"`` and
 ``"foo"`` is translated to ``u"foo"`` and ``b"foo"`` is translated to
 ``"foo"``.
 
+Unlike Python, Hy only recognizes string prefixes (``r``, etc.) in lowercase.
+
 .. _syntax-keywords:
 
 keywords