Add some notes regarding the coercion model

Author: user202729

src/doc/en/reference/coercion/index.rst

@@ -189,17 +189,17 @@ Basic Arithmetic Rules
 Suppose we want to add two element, a and b, whose parents are A and B
 respectively. When we type ``a+b`` then
 
-1. If A ``is`` B, call a._add_(b)
+1. If A ``is`` B, call ``a._add_(b)``
 
-2. If there is a coercion `\phi: B \rightarrow A`, call a._add_( `\phi` (b))
+2. If there is a coercion `\phi\colon B \rightarrow A`, call ``a._add_(`` `\phi` ``(b))``
 
-3. If there is a coercion `\phi: A \rightarrow B`, call `\phi` (a)._add_(b)
+3. If there is a coercion `\phi\colon A \rightarrow B`, call `\phi` ``(a)._add_(b)``
 
-4. Look for `Z` such that there is a coercion `\phi_A: A \rightarrow Z` and
-   `\phi_B: B \rightarrow Z`, call `\phi_A` (a)._add_( `\phi_B` (b))
+4. Look for `Z` such that there is a coercion `\phi_A\colon A \rightarrow Z` and
+   `\phi_B\colon B \rightarrow Z`, call `\phi_A` ``(a)._add_(`` `\phi_B` ``(b))``
 
 These rules are evaluated in order; therefore if there are coercions
-in both directions, then the parent of a._add_b is A -- the parent
+in both directions, then the parent of ``a._add_(b)`` is A -- the parent
 of the left-hand operand is used in such cases.
 
 The same rules are used for subtraction, multiplication, and

src/doc/en/thematic_tutorials/coercion_and_categories.rst

@@ -43,6 +43,15 @@ Outline
   must not be overridden. Instead, the actual implementation should be in
   *single underscore* methods, such as ``_add_`` or ``_mul_``.
 
+  Exceptions are ``__lshift__``, ``__rshift__``, ``__invert__``,
+  where no default implementation is provided.
+
+  Also note that if the class is implemented in Cython, currently
+  SageMath uses a legacy behavior with ``c_api_binop_methods=True``,
+  so the ``self`` argument may not have the correct type
+  in ``__lshift__`` and ``__rshift__``. See
+  `Cython documentation <https://docs.cython.org/en/latest/src/userguide/special_methods.html#arithmetic-methods>`_.
+
 - Turn your parent structure into an object of a category
 
   Declare the category during initialisation\---Your parent structure will
@@ -177,8 +186,8 @@ This basic implementation is formed by the following steps:
 
 - Python uses double\--underscore methods for arithmetic methods and string
   representations. Sage's base classes often have a default implementation,
-  and it is requested to **implement SINGLE underscore methods _repr_, and
-  similarly _add_, _mul_ etc.**
+  and it is requested to **implement SINGLE underscore methods ``_repr_``, and
+  similarly ``_add_``, ``_mul_`` etc.**
 
 - You are encouraged to **make your parent "unique"**. That's to say, parents
   should only evaluate equal if they are identical. Sage provides frameworks
@@ -261,7 +270,7 @@ considerations:
   from those already present in Sage, we use a different string representation.
 
 - Arithmetic is implemented in single\--underscore method ``_add_``, ``_mul_``,
-  etc. **We do not override the default double underscore __add__, __mul__**,
+  etc. **We do not override the default double underscore ``__add__``, ``__mul__``**,
   since otherwise, we could not use Sage's coercion model.
 
 - Comparisons can be implemented using ``_richcmp_``.