DOC: add documentation for total_ordering decorator (GH-4195)

docs/src/userguide/special_methods.rst

@@ -165,14 +165,14 @@ which always take `self` as the first argument.
 Rich comparisons
 -----------------
 
-There are two ways to implement comparison methods.
+There are a few ways to implement comparison methods.
 Depending on the application, one way or the other may be better:
 
-* The first way uses the 6 Python
+* Use 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__`.
+* Use 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
@@ -194,6 +194,25 @@ Depending on the application, one way or the other may be better:
 
   These constants can be cimported from the ``cpython.object`` module.
 
+* Use a ``cython.total_ordering`` decorator, which is a re-implementation of
+  the `functools.total_ordering
+  <https://docs.python.org/3/library/functools.html#functools.total_ordering>`_
+  decorator. It can only be used on a ``cdef`` class:
+
+  .. code-block:: cython
+
+    @cython.total_ordering
+    cdef class ExtGe:
+        cdef int x
+
+        def __ge__(self, other):
+            if not isinstance(other, ExtGe):
+                return NotImplemented
+            return self.x >= (<ExtGe>other).x
+
+        def __eq__(self, other):
+            return isinstance(other, ExtGe) and self.x == (<ExtGe>other).x
+
 .. _the__next__method:
 
 The :meth:`__next__` method