[Python-checkins] cpython (2.7): Issue 22830: Clarify docs for functools.cmp_to_key().

[raymond.hettinger]

https://hg.python.org/cpython/rev/dbe1744ec62e
changeset:   93443:dbe1744ec62e
branch:      2.7
parent:      93439:1cde2bbe841a
user:        Raymond Hettinger <python at rcn.com>
date:        Sun Nov 09 17:10:17 2014 -0800
summary:
  Issue 22830:  Clarify docs for functools.cmp_to_key().

files:
  Doc/library/functools.rst |  11 +++++++----
  1 files changed, 7 insertions(+), 4 deletions(-)


diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -22,8 +22,8 @@
 
 ..  function:: cmp_to_key(func)
 
-   Transform an old-style comparison function to a key function.  Used with
-   tools that accept key functions (such as :func:`sorted`, :func:`min`,
+   Transform an old-style comparison function to a :term:`key function`.  Used
+   with tools that accept key functions (such as :func:`sorted`, :func:`min`,
    :func:`max`, :func:`heapq.nlargest`, :func:`heapq.nsmallest`,
    :func:`itertools.groupby`).  This function is primarily used as a transition
    tool for programs being converted to Python 3 where comparison functions are
@@ -32,13 +32,16 @@
    A comparison function is any callable that accept two arguments, compares them,
    and returns a negative number for less-than, zero for equality, or a positive
    number for greater-than.  A key function is a callable that accepts one
-   argument and returns another value that indicates the position in the desired
-   collation sequence.
+   argument and returns another value to be used as the sort key.
 
    Example::
 
        sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order
 
+   For sorting examples and a brief sorting tutorial, see `Sorting HowTo
+   <https://wiki.python.org/moin/HowTo/Sorting/>`_\.
+
+
    .. versionadded:: 2.7
 
 .. function:: total_ordering(cls)

-- 
Repository URL: https://hg.python.org/cpython