Undeprecate __richcmp__

docs/src/reference/extension_types.rst

@@ -276,15 +276,20 @@ Arithmetic Methods
 Rich Comparisons
 ================
 
-* Starting with Cython 0.27, the Python
+There are two ways to implement comparison methods.
+Depending on the application, one way or the other may be better:
+
+* The first way uses the 6 Python
   `special methods <https://docs.python.org/3/reference/datamodel.html#basic-customization>`_
-  ``__eq__``, ``__lt__``, etc. can be implemented.  In previous versions, ``__richcmp__`` was
-  the only way to implement rich comparisons, but is now deprecated.
-* A single special method called ``__richcmp__()`` can be used to implement all the individual
-  rich compare, special method types.  Note, however, that it is often easier to correctly
-  implement the separate Python special methods than to get the ``__richcmp__()`` method right.
-* ``__richcmp__()`` takes an integer argument, indicating which operation is to be performed
-  as shown in the table below.
+  ``__eq__``, ``__lt__``, etc.
+  This is new since Cython 0.27 and works exactly as in plain Python classes.
+* The second way uses a single special method ``__richcmp__``.
+  This implements all rich comparison operations in one method.
+  The signature is ``def __richcmp__(self, other, int op)`` matching the
+  `PyObject_RichCompare() <https://docs.python.org/3/c-api/object.html#c.PyObject_RichCompare>`_
+  Python/C API function.
+  The integer argument ``op`` indicates which operation is to be performed
+  as shown in the table below:
 
   +-----+-----+-------+
   |  <  |  0  | Py_LT |

docs/src/userguide/special_methods.rst

@@ -127,28 +127,34 @@ take `self` as the first argument.
 Rich comparisons
 -----------------
 
-Starting with Cython 0.27, the Python
-`special methods <https://docs.python.org/3/reference/datamodel.html#basic-customization>`_
-:meth:``__eq__``, :meth:``__lt__``, etc. can be implemented.  In previous versions,
-:meth:``__richcmp__`` was the only way to implement rich comparisons.  It takes an integer
-indicating which operation is to be performed, as follows:
-
-+-----+-----+-------+
-|  <  |  0  | Py_LT |
-+-----+-----+-------+
-| ==  |  2  | Py_EQ |
-+-----+-----+-------+
-|  >  |  4  | Py_GT |
-+-----+-----+-------+
-| <=  |  1  | Py_LE |
-+-----+-----+-------+
-| !=  |  3  | Py_NE |
-+-----+-----+-------+
-| >=  |  5  | Py_GE |
-+-----+-----+-------+
-
-The named constants can be cimported from the ``cpython.object`` module.
-They should generally be preferred over plain integers to improve readabilty.
+There are two ways to implement comparison methods.
+Depending on the application, one way or the other may be better:
+
+* The first way uses the 6 Python
+  `special methods <https://docs.python.org/3/reference/datamodel.html#basic-customization>`_
+  :meth:`__eq__`, :meth:`__lt__`, etc.
+  This is new since Cython 0.27 and works exactly as in plain Python classes.
+* The second way uses a single special method :meth:`__richcmp__`.
+  This implements all rich comparison operations in one method.
+  The signature is ``def __richcmp__(self, other, int op)``.
+  The integer argument ``op`` indicates which operation is to be performed
+  as shown in the table below:
+
+  +-----+-------+
+  |  <  | Py_LT |
+  +-----+-------+
+  | ==  | Py_EQ |
+  +-----+-------+
+  |  >  | Py_GT |
+  +-----+-------+
+  | <=  | Py_LE |
+  +-----+-------+
+  | !=  | Py_NE |
+  +-----+-------+
+  | >=  | Py_GE |
+  +-----+-------+
+
+  These constants can be cimported from the ``cpython.object`` module.
 
 The :meth:`__next__` method
 ----------------------------
@@ -209,6 +215,10 @@ Rich comparison operators
 
 https://docs.python.org/3/reference/datamodel.html#basic-customization
 
+You can choose to either implement the standard Python special methods
+like :meth:`__eq__` or the single special method :meth:`__richcmp__`.
+Depending on the application, one way or the other may be better.
+
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 | __eq__                |self, y                                | object      | self == y                                              |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
@@ -222,13 +232,10 @@ https://docs.python.org/3/reference/datamodel.html#basic-customization
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 | __ge__                |self, y                                | object      | self >= y                                              |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
-| __richcmp__           |x, y, int op                           | object      | Joined rich comparison method for all of the above     |
-|                       |                                       |             | (deprecated, no direct Python equivalent)              |
+| __richcmp__           |self, y, int op                        | object      | Joined rich comparison method for all of the above     |
+|                       |                                       |             | (no direct Python equivalent)                          |
 +-----------------------+---------------------------------------+-------------+--------------------------------------------------------+
 
-New code should better implement the separate Python special methods instead of trying to
-correctly implement the joined ``__richcmp__()`` method.
-
 Arithmetic operators
 ^^^^^^^^^^^^^^^^^^^^