[docs] Document magic methods called by built-in functions (issue 10289)

[vadmium+py at gmail.com]

https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst
File Doc/library/functions.rst (right):

https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst#newcode1289
Doc/library/functions.rst:1289: The items in *iterable* need to be
orderable; otherwise, :exc:`TypeError` is
Actually I think they need to be totally orderable, though TypeError
isn’t going to be raised for partially orderable sequences.

https://bugs.python.org/review/10289/diff/12349/Doc/library/functions.rst#newcode1291
Doc/library/functions.rst:1291: by defining :dfn:`rich comparison
methods` like :meth:`__lt__`, described in
Would be good to be more specific. I suspect it is sufficient to define
the < and > operations, by defining at least one of __lt__() and
__gt__(). And I suspect that many other comparison operations, <=, >=,
==, !=, __eq__(), __le__(), etc, are never used. See also the
list.sort() specification.

https://bugs.python.org/review/10289/