docs: Update special methods table on arithmetic methods. They now have Python semantics.

docs/src/userguide/special_methods.rst

@@ -12,7 +12,7 @@ mention.
 .. Note::
 
     Everything said on this page applies only to extension types, defined
-    with the :keyword:`cdef class` statement. It doesn't apply to classes defined with the
+    with the :keyword:`cdef` class statement. It doesn't apply to classes defined with the
     Python :keyword:`class` statement, where the normal Python rules apply.
 
 .. _declaration:
@@ -152,13 +152,13 @@ Alternatively, the old Cython 0.x (or native C-API) behaviour is still available
 the directive ``c_api_binop_methods=True``.
 
 If you can't handle the combination of types you've been given, you should return
-`NotImplemented`.  This will let Python's operator implementation first try to apply
+``NotImplemented``.  This will let Python's operator implementation first try to apply
 the reversed operator to the second operand, and failing that as well, report an
 appropriate error to the user.
 
 This change in behaviour also applies to the in-place arithmetic method :meth:`__ipow__`.
 It does not apply to any of the other in-place methods (:meth:`__iadd__`, etc.)
-which always take `self` as the first argument.
+which always take ``self`` as the first argument.
 
 .. _rich_comparisons:
 
@@ -307,47 +307,53 @@ Arithmetic operators
 
 https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name 	                | Parameters                            | Return type | 	Description                                 |
-+=======================+=======================================+=============+=====================================================+
-| __add__               | x, y 	                                | object      | binary `+` operator                                 |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __sub__ 	        | x, y 	                                | object      | binary `-` operator                                 |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __mul__ 	        | x, y 	                                | object      | `*` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __div__ 	        | x, y 	                                | object      | `/`  operator for old-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __floordiv__ 	        | x, y 	                                | object      | `//`  operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __truediv__ 	        | x, y 	                                | object      | `/`  operator for new-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __mod__ 	        | x, y 	                                | object      | `%` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __divmod__ 	        | x, y 	                                | object      | combined div and mod                                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __pow__ 	        | x, y, z 	                        | object      | `**` operator or pow(x, y, z)                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __neg__ 	        | self 	                                | object      | unary `-` operator                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __pos__ 	        | self 	                                | object      | unary `+` operator                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __abs__ 	        | self 	                                | object      | absolute value                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __nonzero__ 	        | self 	                                | int 	      | convert to boolean                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __invert__ 	        | self 	                                | object      | `~` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __lshift__ 	        | x, y 	                                | object      | `<<` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __rshift__ 	        | x, y 	                                | object      | `>>` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __and__ 	        | x, y 	                                | object      | `&` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __or__ 	        | x, y 	                                | object      | `|` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __xor__ 	        | x, y 	                                | object      | `^` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| Name 	                      | Parameters         | Return type | 	Description                                 |
++=============================+====================+=============+=====================================================+
+| __add__, __radd__           | self, other        | object      | binary `+` operator                                 |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __sub__, __rsub__           | self, other        | object      | binary `-` operator                                 |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __mul__, __rmul__           | self, other        | object      | `*` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __div__, __rdiv__           | self, other        | object      | `/`  operator for old-style division                |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __floordiv__, __rfloordiv__ | self, other        | object      | `//`  operator                                      |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __truediv__, __rtruediv__   | self, other        | object      | `/`  operator for new-style division                |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __mod__, __rmod__           | self, other        | object      | `%` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __divmod__, __rdivmod__     | self, other        | object      | combined div and mod                                |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __pow__, __rpow__           | self, other, [mod] | object      | `**` operator or pow(x, y, [mod])                   |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __neg__                     | self               | object      | unary `-` operator                                  |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __pos__                     | self               | object      | unary `+` operator                                  |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __abs__                     | self               | object      | absolute value                                      |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __nonzero__ 	              | self               | int 	      | convert to boolean                                  |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __invert__ 	              | self               | object      | `~` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __lshift__, __rlshift__     | self, other        | object      | `<<` operator                                       |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __rshift__, __rrshift__     | self, other        | object      | `>>` operator                                       |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __and__, __rand__           | self, other        | object      | `&` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __or__, __ror__             | self, other        | object      | `|` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+| __xor__, __rxor__           | self, other        | object      | `^` operator                                        |
++-----------------------------+--------------------+-------------+-----------------------------------------------------+
+
+Note that Cython 0.x did not make use of the ``__r...__`` variants and instead
+used the bidirectional C slot signature for the regular methods, thus making the
+first argument ambiguous (not 'self' typed).
+Since Cython 3.0, the operator calls are passed to the respective special methods.
+See `arithmetic_methods`_ above.
 
 Numeric conversions
 ^^^^^^^^^^^^^^^^^^^
@@ -392,7 +398,7 @@ https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types
 +-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
 | __imod__ 	        | self, x 	                        | object      | `%=` operator                                       |
 +-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ipow__ 	        | x, y, z 	                        | object      | `**=` operator                                      |
+| __ipow__ 	        | self, y, z                            | object      | `**=` operator                                      |
 +-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
 | __ilshift__ 	        | self, x 	                        | object      | `<<=` operator                                      |
 +-----------------------+---------------------------------------+-------------+-----------------------------------------------------+