From: Raymond Hettinger <python@rcn.com>
Date: Mon, 10 Nov 2014 01:20:56 +0000 (-0800)
Subject: Issue 22830:  Clarify docs for functools.cmp_to_key().
X-Git-Tag: v3.4.3rc1~340
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=86e9b6b16424ddbdd1a4a393cd295e95835b7ef2;p=thirdparty%2FPython%2Fcpython.git

Issue 22830:  Clarify docs for functools.cmp_to_key().
---

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 7fd7d5826b66..d87fa58dd702 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -21,8 +21,8 @@ The :mod:`functools` module defines the following functions:
 
 .. 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 from Python 2 which supported the use of
@@ -31,13 +31,14 @@ The :mod:`functools` module defines the following functions:
    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 indicating 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 :ref:`sortinghowto`.
+
    .. versionadded:: 3.2