Clean up docstrings

src/galois/_codes/_bch.py

@@ -95,12 +95,14 @@ def __init__(
         r"""
         Constructs a general :math:`\textrm{BCH}(n, k)` code over :math:`\mathrm{GF}(q)`.
 
-        Important:
-            Either `k` or `d` must be provided to define the code. Both may be provided as long as they are consistent.
-
         Arguments:
             n: The codeword size :math:`n`. If :math:`n = q^m - 1`, the BCH code is *primitive*.
             k: The message size :math:`k`.
+
+                .. important::
+                    Either `k` or `d` must be provided to define the code. Both may be provided as long as they are
+                    consistent.
+
             d: The design distance :math:`d`. This defines the number of roots :math:`d - 1` in the generator
                 polynomial :math:`g(x)` over :math:`\mathrm{GF}(q^m)`.
             field: The Galois field :math:`\mathrm{GF}(q)` that defines the alphabet of the codeword symbols.
@@ -766,7 +768,8 @@ def k(self) -> int:
         _CyclicCode.d,
         {},
         r"""
-        The minimum distance of a BCH code may be greater than the design distance, i.e. :math:`d_{min} \ge d`.
+        Notes:
+            The minimum distance of a BCH code may be greater than the design distance, i.e. :math:`d_{min} \ge d`.
 
         Examples:
             Construct a binary :math:`\textrm{BCH}(15, 7)` code.

src/galois/_codes/_cyclic.py

@@ -160,8 +160,9 @@ def generator_poly(self) -> Poly:
         r"""
         The generator polynomial :math:`g(x)` over :math:`\mathrm{GF}(q)`.
 
-        Every codeword :math:`\mathbf{c}` can be represented as a degree-:math:`n` polynomial :math:`c(x)`.
-        Each codeword polynomial :math:`c(x)` is a multiple of :math:`g(x)`.
+        Notes:
+            Every codeword :math:`\mathbf{c}` can be represented as a degree-:math:`n` polynomial :math:`c(x)`.
+            Each codeword polynomial :math:`c(x)` is a multiple of :math:`g(x)`.
         """
         return self._generator_poly
 
@@ -170,7 +171,8 @@ def parity_check_poly(self) -> Poly:
         r"""
         The parity-check polynomial :math:`h(x)`.
 
-        The parity-check polynomial is the generator polynomial of the dual code.
+        Notes:
+            The parity-check polynomial is the generator polynomial of the dual code.
         """
         return self._parity_check_poly
 

src/galois/_codes/_linear.py

@@ -57,16 +57,16 @@ def encode(self, message: ArrayLike, output: Literal["codeword", "parity"] = "co
         r"""
         Encodes the message :math:`\mathbf{m}` into the codeword :math:`\mathbf{c}`.
 
-        .. info::
-            :title: Shortened codes
-
-            For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes), pass :math:`k-s`
-            symbols into :func:`encode` to return the :math:`n-s`-symbol message.
-
         Arguments:
             message: The message as either a :math:`k`-length vector or :math:`(N, k)` matrix, where :math:`N` is the
-                number of messages. For systematic codes, message lengths less than :math:`k` may be provided to
-                produce shortened codewords.
+                number of messages.
+
+                .. info::
+                    :title: Shortened codes
+
+                    For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes),
+                    pass :math:`k-s` symbols into :func:`encode` to return the :math:`n-s`-symbol message.
+
             output: Specify whether to return the codeword or parity symbols only. The default is `"codeword"`.
 
         Returns:
@@ -94,16 +94,15 @@ def detect(self, codeword: ArrayLike) -> bool | np.ndarray:
         r"""
         Detects if errors are present in the codeword :math:`\mathbf{c}`.
 
-        .. info::
-            :title: Shortened codes
-
-            For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes), pass :math:`n-s`
-            symbols into :func:`detect`.
-
         Arguments:
             codeword: The codeword as either a :math:`n`-length vector or :math:`(N, n)` matrix, where :math:`N` is the
-                number of codewords. For systematic codes, codeword lengths less than :math:`n` may be provided for
-                shortened codewords.
+                number of codewords.
+
+                .. info::
+                    :title: Shortened codes
+
+                    For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes),
+                    pass :math:`n-s` symbols into :func:`detect`.
 
         Returns:
             A boolean scalar or :math:`N`-length array indicating if errors were detected in the corresponding codeword.
@@ -138,16 +137,16 @@ def decode(self, codeword, output="message", errors=False):
         r"""
         Decodes the codeword :math:`\mathbf{c}` into the message :math:`\mathbf{m}`.
 
-        .. info::
-            :title: Shortened codes
+        Arguments:
+            codeword: The codeword as either a :math:`n`-length vector or :math:`(N, n)` matrix, where :math:`N` is the
+                number of codewords.
 
-            For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes), pass :math:`n-s`
-            symbols into :func:`decode` to return the :math:`k-s`-symbol message.
+                .. info::
+                    :title: Shortened codes
+
+                    For the shortened :math:`[n-s,\ k-s,\ d]` code (only applicable for systematic codes),
+                    pass :math:`n-s` symbols into :func:`decode` to return the :math:`k-s`-symbol message.
 
-        Arguments:
-            codeword: he codeword as either a :math:`n`-length vector or :math:`(N, n)` matrix, where :math:`N` is the
-                number of codewords. For systematic codes, codeword lengths less than :math:`n` may be provided for
-                shortened codewords.
             output: Specify whether to return the error-corrected message or entire codeword. The default is
                 `"message"`.
             errors: Optionally specify whether to return the number of corrected errors. The default is `False`.
@@ -333,11 +332,13 @@ def d(self) -> int:
     @property
     def t(self) -> int:
         r"""
-        The error-correcting capability :math:`t` of the code. The code can correct :math:`t` symbol errors in
-        a codeword.
+        The error-correcting capability :math:`t` of the code.
+
+        Notes:
+            The code can correct :math:`t` symbol errors in a codeword.
 
-        .. math::
-            t = \bigg\lfloor \frac{d - 1}{2} \bigg\rfloor
+            .. math::
+                t = \bigg\lfloor \frac{d - 1}{2} \bigg\rfloor
         """
         return (self.d - 1) // 2
 

src/galois/_codes/_reed_solomon.py

@@ -90,12 +90,14 @@ def __init__(
         r"""
         Constructs a general :math:`\textrm{RS}(n, k)` code over :math:`\mathrm{GF}(q)`.
 
-        Important:
-            Either `k` or `d` must be provided to define the code. Both may be provided as long as they are consistent.
-
         Arguments:
             n: The codeword size :math:`n`. If :math:`n = q - 1`, the Reed-Solomon code is *primitive*.
             k: The message size :math:`k`.
+
+                .. important::
+                    Either `k` or `d` must be provided to define the code. Both may be provided as long as they are
+                    consistent.
+
             d: The design distance :math:`d`. This defines the number of roots :math:`d - 1` in the generator
                 polynomial :math:`g(x)` over :math:`\mathrm{GF}(q)`. Reed-Solomon codes achieve the Singleton bound,
                 so :math:`d = n - k + 1`.

src/galois/_domains/_array.py

@@ -367,27 +367,25 @@ def repr(cls, element_repr: Literal["int", "poly", "power"] = "int") -> Generato
         r"""
         Sets the element representation for all arrays from this :obj:`~galois.FieldArray` subclass.
 
-        The element representation can be set to either the integer, polynomial, or power representation.
-        See :doc:`/basic-usage/element-representation` for a further discussion.
-
-        This function updates :obj:`~galois.FieldArray.element_repr`.
-
-        .. danger::
-
-            For the power representation, :func:`numpy.log` is computed on each element. So for large fields without
-            lookup tables, displaying arrays in the power representation may take longer than expected.
-
         Arguments:
             element_repr: The field element representation.
 
                 - `"int"` (default): Sets the representation to the :ref:`integer representation <int-repr>`.
                 - `"poly"`: Sets the representation to the :ref:`polynomial representation <poly-repr>`.
                 - `"power"`: Sets the representation to the :ref:`power representation <power-repr>`.
 
+                .. danger::
+
+                    For the power representation, :func:`numpy.log` is computed on each element. So for large fields
+                    without lookup tables, displaying arrays in the power representation may take longer than expected.
+
         Returns:
             A context manager for use in a `with` statement. If permanently setting the element representation,
             disregard the return value.
 
+        Notes:
+            This function updates :obj:`~galois.FieldArray.element_repr`.
+
         Examples:
             The default element representation is the integer representation.
 

src/galois/_fields/_array.py

@@ -378,8 +378,6 @@ def Vector(cls, array: ArrayLike, dtype: DTypeLike | None = None) -> FieldArray:
         Creates an array over :math:`\mathrm{GF}(p^m)` from length-:math:`m` vectors over the prime subfield
         :math:`\mathrm{GF}(p)`.
 
-        This function is the inverse operation of the :func:`vector` method.
-
         Arguments:
             array: An array over :math:`\mathrm{GF}(p)` with last dimension :math:`m`. An array with shape
                 `(n1, n2, m)` has output shape `(n1, n2)`. By convention, the vectors are ordered from degree
@@ -391,6 +389,9 @@ def Vector(cls, array: ArrayLike, dtype: DTypeLike | None = None) -> FieldArray:
         Returns:
             An array over :math:`\mathrm{GF}(p^m)`.
 
+        Notes:
+            This method is the inverse of the :func:`vector` method.
+
         Examples:
             .. ipython-with-reprs:: int,poly,power
 
@@ -908,9 +909,6 @@ def vector(self, dtype: DTypeLike | None = None) -> FieldArray:
         Converts an array over :math:`\mathrm{GF}(p^m)` to length-:math:`m` vectors over the prime subfield
         :math:`\mathrm{GF}(p)`.
 
-        This function is the inverse operation of the :func:`Vector` constructor. For an array with shape `(n1, n2)`,
-        the output shape is `(n1, n2, m)`. By convention, the vectors are ordered from degree :math:`m-1` to degree 0.
-
         Arguments:
             dtype: The :obj:`numpy.dtype` of the array elements. The default is `None` which represents the smallest
                 unsigned data type for this :obj:`~galois.FieldArray` subclass (the first element in
@@ -919,6 +917,11 @@ def vector(self, dtype: DTypeLike | None = None) -> FieldArray:
         Returns:
             An array over :math:`\mathrm{GF}(p)` with last dimension :math:`m`.
 
+        Notes:
+            This method is the inverse of the :func:`Vector` constructor. For an array with shape `(n1, n2)`,
+            the output shape is `(n1, n2, m)`. By convention, the vectors are ordered from degree :math:`m-1`
+            to degree 0.
+
         Examples:
             .. ipython-with-reprs:: int,poly,power
 
@@ -1349,15 +1352,15 @@ def characteristic_poly(self) -> Poly:
         Computes the characteristic polynomial of a finite field element :math:`a` or a square matrix
         :math:`\mathbf{A}`.
 
-        Important:
-            This function may only be invoked on a single finite field element (scalar 0-D array) or a square
-            :math:`n \times n` matrix (2-D array).
-
         Returns:
             For scalar inputs, the degree-:math:`m` characteristic polynomial :math:`c_a(x)` of :math:`a` over
             :math:`\mathrm{GF}(p)`. For square :math:`n \times n` matrix inputs, the degree-:math:`n` characteristic
             polynomial :math:`c_A(x)` of :math:`\mathbf{A}` over :math:`\mathrm{GF}(p^m)`.
 
+        Raises:
+            ValueError: If the array is not a single finite field element (scalar 0-D array) or a square
+                :math:`n \times n` matrix (2-D array).
+
         Notes:
             An element :math:`a` of :math:`\mathrm{GF}(p^m)` has characteristic polynomial :math:`c_a(x)` over
             :math:`\mathrm{GF}(p)`. The characteristic polynomial when evaluated in :math:`\mathrm{GF}(p^m)`
@@ -1411,12 +1414,13 @@ def minimal_poly(self) -> Poly:
         r"""
         Computes the minimal polynomial of a finite field element :math:`a`.
 
-        Important:
-            This function may only be invoked on a single finite field element (scalar 0-D array).
-
         Returns:
             For scalar inputs, the minimal polynomial :math:`m_a(x)` of :math:`a` over :math:`\mathrm{GF}(p)`.
 
+        Raises:
+            NotImplementedError: If the array is a a square :math:`n \times n` matrix (2-D array).
+            ValueError: If the array is not a single finite field element (scalar 0-D array).
+
         Notes:
             An element :math:`a` of :math:`\mathrm{GF}(p^m)` has minimal polynomial :math:`m_a(x)` over
             :math:`\mathrm{GF}(p)`. The minimal polynomial when evaluated in :math:`\mathrm{GF}(p^m)` annihilates
@@ -1443,8 +1447,9 @@ def minimal_poly(self) -> Poly:
         """
         if self.ndim == 0:
             return _minimal_poly_element(self)
-        # if self.ndim == 2:
-        #     return _minimal_poly_matrix(self)
+        if self.ndim == 2:
+            raise NotImplementedError("Computing the minimal polynomial of a matrix is not yet implemented.")
+            # return _minimal_poly_matrix(self)
         raise ValueError(
             f"The array must be either 0-D to return the minimal polynomial of a single element "
             f"or 2-D to return the minimal polynomial of a square matrix, not have shape {self.shape}."
@@ -1454,16 +1459,16 @@ def log(self, base: ElementLike | ArrayLike | None = None) -> int | np.ndarray:
         r"""
         Computes the logarithm of the array :math:`x` base :math:`\beta`.
 
-        .. danger::
-
-            If the Galois field is configured to use lookup tables, `ufunc_mode == "jit-lookup"`, and this function
-            is invoked with a base different from :obj:`~FieldArray.primitive_element`, then explicit calculation will
-            be used (which is slower than lookup tables).
-
         Arguments:
-            base: A primitive element(s) :math:`\beta` of the finite field that is the base of the logarithm.
+            base: A primitive element or elements :math:`\beta` of the finite field that is the base of the logarithm.
                 The default is `None` which uses :obj:`~FieldArray.primitive_element`.
 
+                .. danger::
+
+                    If the Galois field is configured to use lookup tables (`ufunc_mode == "jit-lookup"`) and this
+                    method is invoked with a base different from :obj:`~FieldArray.primitive_element`, then explicit
+                    calculation will be used (which is slower than using lookup tables).
+
         Returns:
             An integer array :math:`i` of powers of :math:`\beta` such that :math:`\beta^i = x`. The return array
             shape obeys NumPy broadcasting rules.
@@ -1537,7 +1542,8 @@ def __repr__(self) -> str:
         """
         Displays the array specifying the class and finite field order.
 
-        This function prepends `GF(` and appends `, order=p^m)`.
+        Notes:
+            This function prepends `GF(` and appends `, order=p^m)`.
 
         Examples:
             .. ipython-with-reprs:: int,poly,power
@@ -1552,7 +1558,8 @@ def __str__(self) -> str:
         """
         Displays the array without specifying the class or finite field order.
 
-        This function does not prepend `GF(` and or append `, order=p^m)`. It also omits the comma separators.
+        Notes:
+            This function does not prepend `GF(` and or append `, order=p^m)`. It also omits the comma separators.
 
         Examples:
             .. ipython-with-reprs:: int,poly,power