Improve docstrings

1 files changed, 22 insertions, 3 deletions

diff --git a/mdpoly/algebra.py b/mdpoly/algebra.py
index 4342a5e..480a904 100644
--- a/mdpoly/algebra.py
+++ b/mdpoly/algebra.py
@@ -139,7 +139,7 @@ def unary_operator(inner_type: AlgebraicStructure):
     *right* contains a placeholder :py:class:`mdpoly.leaves.Nothing`,
     furthermore a new field *inner* is added as alias to *left*.
 
-    See also :py:fun:`mdpoly.algebra.binary_operator`.
+    See also :py:func:`mdpoly.algebra.binary_operator`.
     """
     def decorator(cls: Expr) -> Expr:
         """ Class decorator to modify constructor of unary operators. """
@@ -239,7 +239,11 @@ class Exp(Expr, ReducibleExpr):
 # ╹  ┗━┛┗━╸ ╹ ╹ ╹┗━┛╹ ╹╹╹ ╹┗━╸   ╹ ╹┗━╸┗━┛┗━╸┗━┛╹┗╸╹ ╹
 
 class PolyRingAlgebra(AlgebraicStructure, Protocol):
-    """ Endows with the algebraic structure of a polynomial ring. """
+    r""" Endows with the algebraic structure of a polynomial ring.
+
+    This is the algebra of :math:`\mathbb{R}[x_1, \ldots, x_n]`. Note that the
+    polynomials are scalars.
+    """
     _algebra = AlgebraicStructure.Algebra.poly_ring
     _parameter = Param
     _constant = Const
@@ -367,7 +371,22 @@ class RationalFieldAlgebra(AlgebraicStructure, Protocol):
 # ╹ ╹╹ ╹ ╹ ╹┗╸╹╹ ╹   ╹ ╹┗━╸┗━┛┗━╸┗━┛╹┗╸╹ ╹
 
 class MatrixAlgebra(AlgebraicStructure, Protocol):
-    """ Endows with the algebraic structure of a matrix ring. """
+    r""" Endows with the algebraic structure of a matrix ring and / or module
+    depending on the shape.
+
+    We denote with :math:`R` a polynomial ring.
+
+    - If the shape is square, like :math:`(n, n)` then this is :math:`M_n(R)`
+      the ring of matrices over :math:`R`.
+
+    - If the shape is something else like a row or column (:math:`(m, p)`,
+      :math:`(1, n)` or :math:`(n, 1)`) this is a module, i.e. an algebra with
+      addition and scalar multiplication, where the "scalars" come from
+      :math:`R`.
+    
+    Furthermore some operators that are usually expected from matrices are
+    already included (eg. transposition).
+    """
 
     _algebra = AlgebraicStructure.Algebra.matrix_ring
     # FIXME: consider MatParam or something like that?