Improve mod docs.

1 files changed, 41 insertions, 2 deletions

diff --git a/pyecsca/ec/mod.py b/pyecsca/ec/mod.py
index 4221a93..7637fd4 100644
--- a/pyecsca/ec/mod.py
+++ b/pyecsca/ec/mod.py
@@ -5,7 +5,8 @@ The base class :py:class:`Mod` dynamically
 dispatches to the implementation chosen by the runtime configuration of the library
 (see :py:class:`pyecsca.misc.cfg.Config`). A Python integer based implementation is available under
 :py:class:`RawMod`. A symbolic implementation based on sympy is available under :py:class:`SymbolicMod`. If
-`gmpy2` is installed, a GMP based implementation is available under :py:class:`GMPMod`.
+`gmpy2` is installed, a GMP based implementation is available under :py:class:`GMPMod`. If `python-flint` is
+installed, a flint based implementation is available under :py:class:`FlintMod`.
 """
 import random
 import secrets
@@ -162,7 +163,40 @@ _mod_order = ["gmp", "flint", "python"]
 
 @public
 class Mod:
-    """An element x of ℤₙ."""
+    """
+    An element x of ℤₙ.
+
+    .. note::
+        This class dispatches to one of :py:class:`RawMod`, :py:class:`GMPMod` or :py:class:`FlintMod`
+        based on what packages are installed and what implementation is configured (see
+        :py:module:`pyecsca.misc.cfg`).
+
+    Has all the usual special methods that upcast integers automatically:
+
+    >>> a = Mod(3, 5)
+    >>> b = Mod(2, 5)
+    >>> a + b
+    0
+    >>> a * 2
+    1
+    >>> a == 3
+    True
+    >>> a == -2
+    True
+    >>> -a
+    2
+
+    Plus some additional useful things:
+
+    >>> a.inverse()
+    2
+    >>> a.is_residue()
+    False
+    >>> (a**2).is_residue()
+    True
+    >>> (a**2).sqrt() == a
+    True
+    """
 
     x: Any
     n: Any
@@ -204,6 +238,11 @@ class Mod:
         return self.__class__(self.n - self.x, self.n)
 
     def bit_length(self):
+        """
+        Compute the bit length of this element (in its positive integer representation).
+
+        :return: The bit-length.
+        """
         raise NotImplementedError
 
     def inverse(self) -> "Mod":