trunk merge

Doc/glossary.rst

@@ -41,7 +41,7 @@ Glossary
 
    argument
       A value passed to a :term:`function` (or :term:`method`) when calling the
-      function.  There are two types of arguments:
+      function.  There are two kinds of argument:
 
       * :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
         ``name=``) in a function call or passed as a value in a dictionary
@@ -601,7 +601,7 @@ Glossary
    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:
+      function can accept.  There are five kinds of parameter:
 
       * :dfn:`positional-or-keyword`: specifies an argument that can be passed
         either :term:`positionally <argument>` or as a :term:`keyword argument
@@ -615,6 +615,8 @@ Glossary
         parameters.  However, some built-in functions have positional-only
         parameters (e.g. :func:`abs`).
 
+      .. _keyword-only_parameter:
+
       * :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

Doc/library/asynchat.rst

@@ -10,8 +10,10 @@
 
 --------------
 
-Note: This module exists for backwards compatibility only.  For new code we
-recommend using :module:`asyncio`.
+.. note::
+
+   This module exists for backwards compatibility only.  For new code we
+   recommend using :mod:`asyncio`.
 
 This module builds on the :mod:`asyncore` infrastructure, simplifying
 asynchronous clients and servers and making it easier to handle protocols

Doc/library/asyncore.rst

@@ -13,8 +13,10 @@
 
 --------------
 
-Note: This module exists for backwards compatibility only.  For new code we
-recommend using :module:`asyncio`.
+.. note::
+
+   This module exists for backwards compatibility only.  For new code we
+   recommend using :mod:`asyncio`.
 
 This module provides the basic infrastructure for writing asynchronous  socket
 service clients and servers.

Doc/library/stdtypes.rst

@@ -1149,6 +1149,9 @@ application).
       fail, the entire sort operation will fail (and the list will likely be left
       in a partially modified state).
 
+      :meth:`sort` accepts two arguments that can only be passed by keyword
+      (:ref:`keyword-only arguments <keyword-only_parameter>`):
+
       *key* specifies a function of one argument that is used to extract a
       comparison key from each list element (for example, ``key=str.lower``).
       The key corresponding to each item in the list is calculated once and

Misc/NEWS

@@ -352,6 +352,13 @@ Tests
 
 - Issue 19384: Fix test_py_compile for root user, patch by Claudiu Popa.
 
+Documentation
+-------------
+
+- Issue #18326: Clarify that list.sort's arguments are keyword-only.  Also,
+  attempt to reduce confusion in the glossary by not saying there are
+  different "types" of arguments and parameters.
+
 Build
 -----