[Python-checkins] [3.6] bpo-30085: Improve documentation for operator (GH-1171) (#3736)

[Terry Jan Reedy]

https://github.com/python/cpython/commit/d38caf68bb417232fb0ccecb5558d7d0ca4a9507
commit: d38caf68bb417232fb0ccecb5558d7d0ca4a9507
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Terry Jan Reedy <tjreedy at udel.edu>
date: 2017-09-24T17:13:15-04:00
summary:

[3.6] bpo-30085: Improve documentation for operator (GH-1171) (#3736)

The dunderless functions are preferred; dunder are retained for back compatilibity.
Patch by Sanket Dasgupta.
(cherry picked from commit 5b9299d8c72aeadccadd77e4b8132094ba9a1f96)

files:
A Misc/NEWS.d/next/Documentation/2017-09-14-18-44-50.bpo-30085.0J9w-u.rst
M Doc/library/operator.rst

diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index 8121b480cb6..60bf23a549b 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -17,9 +17,10 @@
 
 The :mod:`operator` module exports a set of efficient functions corresponding to
 the intrinsic operators of Python.  For example, ``operator.add(x, y)`` is
-equivalent to the expression ``x+y``.  The function names are those used for
-special class methods; variants without leading and trailing ``__`` are also
-provided for convenience.
+equivalent to the expression ``x+y``. Many function names are those used for
+special methods, without the double underscores.  For backward compatibility,
+many of these have a variant with the double underscores kept. The variants
+without the double underscores are preferred for clarity.
 
 The functions fall into categories that perform object comparisons, logical
 operations, mathematical operations and sequence operations.
diff --git a/Misc/NEWS.d/next/Documentation/2017-09-14-18-44-50.bpo-30085.0J9w-u.rst b/Misc/NEWS.d/next/Documentation/2017-09-14-18-44-50.bpo-30085.0J9w-u.rst
new file mode 100644
index 00000000000..c8be050009c
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2017-09-14-18-44-50.bpo-30085.0J9w-u.rst
@@ -0,0 +1,2 @@
+The operator functions without double underscores are preferred for clarity.
+The one with underscores are only kept for back-compatibility.