Improve argument/parameter documentation (issue #15990).

This commit adds "parameter" to the glossary, improves and consolidates the
"argument" glossary entry, and adds a question to the FAQ on the difference
between arguments and parameters.

3 files changed, 99 insertions, 18 deletions

diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index d33e25b..2d5d2b1 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -313,6 +313,27 @@ calling another function by using ``*`` and ``**``::
        g(x, *args, **kwargs)
 
 
+.. _faq-argument-vs-parameter:
+
+What is the difference between arguments and parameters?
+--------------------------------------------------------
+
+:term:`Parameters <parameter>` are defined by the names that appear in a
+function definition, whereas :term:`arguments <argument>` are the values
+actually passed to a function when calling it.  Parameters define what types of
+arguments a function can accept.  For example, given the function definition::
+
+   def func(foo, bar=None, **kwargs):
+       pass
+
+*foo*, *bar* and *kwargs* are parameters of ``func``.  However, when calling
+``func``, for example::
+
+   func(42, bar=314, extra=somevar)
+
+the values ``42``, ``314``, and ``somevar`` are arguments.
+
+
 How do I write a function with output parameters (call by reference)?
 ---------------------------------------------------------------------
 
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 3c11de7..ddecc09 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -40,16 +40,34 @@ Glossary
       ABCs with the :mod:`abc` module.
 
    argument
-      A value passed to a function or method, assigned to a named local
-      variable in the function body.  A function or method may have both
-      positional arguments and keyword arguments in its definition.
-      Positional and keyword arguments may be variable-length: ``*`` accepts
-      or passes (if in the function definition or call) several positional
-      arguments in a list, while ``**`` does the same for keyword arguments
-      in a dictionary.
+      A value passed to a :term:`function` (or :term:`method`) when calling the
+      function.  There are two types of arguments:
+
+      * :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
+        ``name=``) in a function call or passed as a value in a dictionary
+        preceded by ``**``.  For example, ``3`` and ``5`` are both keyword
+        arguments in the following calls to :func:`complex`::
+
+           complex(real=3, imag=5)
+           complex(**{'real': 3, 'imag': 5})
+
+      * :dfn:`positional argument`: an argument that is not a keyword argument.
+        Positional arguments can appear at the beginning of an argument list
+        and/or be passed as elements of an :term:`iterable` preceded by ``*``.
+        For example, ``3`` and ``5`` are both positional arguments in the
+        following calls::
+
+           complex(3, 5)
+           complex(*(3, 5))
 
-      Any expression may be used within the argument list, and the evaluated
-      value is passed to the local variable.
+      Arguments are assigned to the named local variables in a function body.
+      See the :ref:`calls` section for the rules governing this assignment.
+      Syntactically, any expression can be used to represent an argument; the
+      evaluated value is assigned to the local variable.
+
+      See also the :term:`parameter` glossary entry, the FAQ question on
+      :ref:`the difference between arguments and parameters
+      <faq-argument-vs-parameter>`, and :pep:`362`.
 
    attribute
       A value associated with an object which is referenced by name using
@@ -391,10 +409,7 @@ Glossary
       <sortinghowto>` for examples of how to create and use key functions.
 
    keyword argument
-      Arguments which are preceded with a ``variable_name=`` in the call.
-      The variable name designates the local name in the function to which the
-      value is assigned.  ``**`` is used to accept or pass a dictionary of
-      keyword arguments.  See :term:`argument`.
+      See :term:`argument`.
 
    lambda
       An anonymous inline function consisting of a single :term:`expression`
@@ -516,12 +531,55 @@ Glossary
       (methods).  Also the ultimate base class of any :term:`new-style
       class`.
 
+   parameter
+      A named entity in a :term:`function` (or method) definition that
+      specifies an :term:`argument` (or in some cases, arguments) that the
+      function can accept.  There are five types of parameters:
+
+      * :dfn:`positional-or-keyword`: specifies an argument that can be passed
+        either :term:`positionally <argument>` or as a :term:`keyword argument
+        <argument>`.  This is the default kind of parameter, for example *foo*
+        and *bar* in the following::
+
+           def func(foo, bar=None): ...
+
+      * :dfn:`positional-only`: specifies an argument that can be supplied only
+        by position.  Python has no syntax for defining positional-only
+        parameters.  However, some built-in functions have positional-only
+        parameters (e.g. :func:`abs`).
+
+      * :dfn:`keyword-only`: specifies an argument that can be supplied only
+        by keyword.  Keyword-only parameters can be defined by including a
+        single var-positional parameter or bare ``*`` in the parameter list
+        of the function definition before them, for example *kw_only1* and
+        *kw_only2* in the following::
+
+           def func(arg, *, kw_only1, kw_only2): ...
+
+      * :dfn:`var-positional`: specifies that an arbitrary sequence of
+        positional arguments can be provided (in addition to any positional
+        arguments already accepted by other parameters).  Such a parameter can
+        be defined by prepending the parameter name with ``*``, for example
+        *args* in the following::
+
+           def func(*args, **kwargs): ...
+
+      * :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
+        can be provided (in addition to any keyword arguments already accepted
+        by other parameters).  Such a parameter can be defined by prepending
+        the parameter name with ``**``, for example *kwargs* in the example
+        above.
+
+      Parameters can specify both optional and required arguments, as well as
+      default values for some optional arguments.
+
+      See also the :term:`argument` glossary entry, the FAQ question on
+      :ref:`the difference between arguments and parameters
+      <faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
+      :ref:`function` section, and :pep:`362`.
+
    positional argument
-      The arguments assigned to local names inside a function or method,
-      determined by the order in which they were given in the call.  ``*`` is
-      used to either accept multiple positional arguments (when in the
-      definition), or pass several arguments as a list to a function.  See
-      :term:`argument`.
+      See :term:`argument`.
 
    Python 3000
       Nickname for the Python 3.x release line (coined long ago when the release
diff --git a/Misc/NEWS b/Misc/NEWS
index 0b6e917..5fe7fc2 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -741,6 +741,8 @@ Tools/Demos
 Documentation
 -------------
 
+- Issue #15990: Improve argument/parameter documentation.
+
 - Issue #13538: Improve str() and object.__str__() documentation.
 
 - Issue #16400: Update the description of which versions of a given package