gh-37790: Improve docstrings in groups

I parsed the `groups`  module like a _robot_ and I edited the
docstrings. (e.g. 1-line outputs, self to ``self``)

### ⌛ Dependencies

Depends on #37789.

URL: #37790
Reported by: gmou3
Reviewer(s): Matthias Köppe

build/pkgs/configure/checksums.ini

@@ -1,4 +1,4 @@
 tarball=configure-VERSION.tar.gz
-sha1=84471145bab92334f2220717f26487f2134ef8bb
-md5=306dee709dd7b945c378393b1e69d876
-cksum=2975864856
+sha1=f46d28f976fdd73aa93eff6810b28b3e7b165bf1
+md5=db30b8d7485d8c3b6f4f73a8282816be
+cksum=726460493

build/pkgs/configure/package-version.txt

@@ -1 +1 @@
-62f58efeda6b4ef3898bfd0c020b6ec3c6befd72
+3cffb4c1c8d29849cfeb9dc0332d7549800e044a

src/sage/groups/abelian_gps/abelian_aut.py

@@ -176,9 +176,7 @@ def matrix(self):
         The `i`-th row is the exponent vector of
         the image of the `i`-th generator.
 
-        OUTPUT:
-
-        - a square matrix over the integers
+        OUTPUT: a square matrix over the integers
 
         EXAMPLES::
 
@@ -315,9 +313,7 @@ def _coerce_map_from_(self, S):
 
         - ``S`` -- anything
 
-        OUTPUT:
-
-        Boolean or nothing
+        OUTPUT: boolean or nothing
 
         EXAMPLES::
 

src/sage/groups/abelian_gps/abelian_group.py

@@ -40,21 +40,21 @@
 invariant factors of the group. You should now use
 :meth:`~AbelianGroup_class.gens_orders` instead::
 
-   sage: J = AbelianGroup([2,0,3,2,4]);  J
-   Multiplicative Abelian group isomorphic to C2 x Z x C3 x C2 x C4
-   sage: J.gens_orders()            # use this instead
-   (2, 0, 3, 2, 4)
-   sage: J.invariants()             # deprecated
-   (2, 0, 3, 2, 4)
-   sage: J.elementary_divisors()    # these are the "invariant factors"
-   (2, 2, 12, 0)
-   sage: for i in range(J.ngens()):
-   ....:     print((i, J.gen(i), J.gen(i).order()))     # or use this form
-   (0, f0, 2)
-   (1, f1, +Infinity)
-   (2, f2, 3)
-   (3, f3, 2)
-   (4, f4, 4)
+    sage: J = AbelianGroup([2,0,3,2,4]);  J
+    Multiplicative Abelian group isomorphic to C2 x Z x C3 x C2 x C4
+    sage: J.gens_orders()            # use this instead
+    (2, 0, 3, 2, 4)
+    sage: J.invariants()             # deprecated
+    (2, 0, 3, 2, 4)
+    sage: J.elementary_divisors()    # these are the "invariant factors"
+    (2, 2, 12, 0)
+    sage: for i in range(J.ngens()):
+    ....:     print((i, J.gen(i), J.gen(i).order()))     # or use this form
+    (0, f0, 2)
+    (1, f1, +Infinity)
+    (2, f2, 3)
+    (3, f3, 2)
+    (4, f4, 4)
 
 Background on invariant factors and the Smith normal form
 (according to section 4.1 of [Cohen1]_): An abelian group is a
@@ -160,7 +160,7 @@
 .. [Rotman] \J. Rotman, An introduction to the theory of
   groups, 4th ed, Springer, 1995.
 
-.. warning::
+.. WARNING::
 
    Many basic properties for infinite abelian groups are not
    implemented.
@@ -221,15 +221,17 @@
 from sage.structure.unique_representation import UniqueRepresentation
 
 
-# TODO: this uses perm groups - the AbelianGroupElement instance method
-# uses a different implementation.
+# .. TODO::
+
+#     this uses perm groups - the AbelianGroupElement instance method
+#     uses a different implementation.
 def word_problem(words, g, verbose=False):
     r"""
-    G and H are abelian, g in G, H is a subgroup of G generated by a
-    list (words) of elements of G. If g is in H, return the expression
-    for g as a word in the elements of (words).
+    `G` and `H` are abelian, `g` in `G`, `H` is a subgroup of `G` generated by
+    a list (words) of elements of `G`. If `g` is in `H`, return the expression
+    for `g` as a word in the elements of (words).
 
-    The 'word problem' for a finite abelian group G boils down to the
+    The 'word problem' for a finite abelian group `G` boils down to the
     following matrix-vector analog of the Chinese remainder theorem.
 
     Problem: Fix integers `1<n_1\leq n_2\leq ...\leq n_k`
@@ -289,7 +291,7 @@ def word_problem(words, g, verbose=False):
         sage: word_problem([a,b,c,d,e], b)
         [[b, 1]]
 
-    .. warning::
+    .. WARNING::
 
        1. Might have unpleasant effect when the word problem
           cannot be solved.
@@ -448,7 +450,7 @@ def AbelianGroup(n, gens_orders=None, names="f"):
 
 def is_AbelianGroup(x):
     """
-    Return True if ``x`` is an Abelian group.
+    Return ``True`` if ``x`` is an Abelian group.
 
     EXAMPLES::
 
@@ -467,7 +469,7 @@ class AbelianGroup_class(UniqueRepresentation, AbelianGroupBase):
     """
     The parent for Abelian groups with chosen generator orders.
 
-    .. warning::
+    .. WARNING::
 
         You should use :func:`AbelianGroup` to construct Abelian
         groups and not instantiate this class directly.
@@ -518,7 +520,7 @@ class AbelianGroup_class(UniqueRepresentation, AbelianGroupBase):
 
     def __init__(self, generator_orders, names, category=None):
         """
-        The Python constructor
+        The Python constructor.
 
         TESTS::
 
@@ -552,15 +554,13 @@ def __init__(self, generator_orders, names, category=None):
 
     def is_isomorphic(left, right):
         """
-        Check whether ``left`` and ``right`` are isomorphic
+        Check whether ``left`` and ``right`` are isomorphic.
 
         INPUT:
 
         - ``right`` -- anything.
 
-        OUTPUT:
-
-        Boolean. Whether ``left`` and ``right`` are isomorphic as abelian groups.
+        OUTPUT: boolean; whether ``left`` and ``right`` are isomorphic as abelian groups
 
         EXAMPLES::
 
@@ -601,7 +601,7 @@ def is_subgroup(left, right):
 
     def __ge__(left, right):
         """
-        Test whether ``right`` is a subgroup of ``left``
+        Test whether ``right`` is a subgroup of ``left``.
 
         EXAMPLES::
 
@@ -614,7 +614,7 @@ def __ge__(left, right):
 
     def __lt__(left, right):
         """
-        Test whether ``left`` is a strict subgroup of ``right``
+        Test whether ``left`` is a strict subgroup of ``right``.
 
         EXAMPLES::
 
@@ -627,7 +627,7 @@ def __lt__(left, right):
 
     def __gt__(left, right):
         """
-        Test whether ``right`` is a strict subgroup of ``left``
+        Test whether ``right`` is a strict subgroup of ``left``.
 
         EXAMPLES::
 
@@ -640,7 +640,7 @@ def __gt__(left, right):
 
     def is_trivial(self):
         """
-        Return whether the group is trivial
+        Return whether the group is trivial.
 
         A group is trivial if it has precisely one element.
 
@@ -682,9 +682,7 @@ def dual_group(self, names="X", base_ring=None):
         - ``base_ring`` -- the base ring. If ``None`` (default), then
           a suitable cyclotomic field is picked automatically.
 
-        OUTPUT:
-
-        The :class:`dual abelian group <sage.groups.abelian_gps.dual_abelian_group.DualAbelianGroup_class>`.
+        OUTPUT: the :class:`dual abelian group <sage.groups.abelian_gps.dual_abelian_group.DualAbelianGroup_class>`
 
         EXAMPLES::
 
@@ -719,9 +717,9 @@ def dual_group(self, names="X", base_ring=None):
     @cached_method
     def elementary_divisors(self):
         r"""
-        This returns the elementary divisors of the group, using Pari.
+        Return the elementary divisors of the group, using Pari.
 
-        .. note::
+        .. NOTE::
 
             Here is another algorithm for computing the elementary divisors
             `d_1, d_2, d_3, \ldots`, of a finite abelian group (where `d_1 | d_2 | d_3 | \ldots`
@@ -736,9 +734,7 @@ def elementary_divisors(self):
             on these "smaller invariants" to compute `d_{i-1}`, and so on.
             (Thanks to Robert Miller for communicating this algorithm.)
 
-        OUTPUT:
-
-        A tuple of integers.
+        OUTPUT: tuple of integers
 
         EXAMPLES::
 
@@ -806,15 +802,13 @@ def identity(self):
 
     def _group_notation(self, eldv):
         """
-        Return abstract group notation for generator orders ``eldv``
+        Return abstract group notation for generator orders ``eldv``.
 
         INPUT:
 
-        - ``eldv`` -- iterable of integers.
-
-        OUTPUT:
+        - ``eldv`` -- iterable of integers
 
-        String.
+        OUTPUT: string
 
         EXAMPLES::
 
@@ -955,9 +949,7 @@ def gens_orders(self):
         Use :meth:`elementary_divisors` if you are looking for an
         invariant of the group.
 
-        OUTPUT:
-
-        A tuple of integers.
+        OUTPUT: tuple of integers
 
         EXAMPLES::
 
@@ -1018,9 +1010,7 @@ def invariants(self):
         Use :meth:`elementary_divisors` if you are looking for an
         invariant of the group.
 
-        OUTPUT:
-
-        A tuple of integers. Zero means infinite cyclic factor.
+        OUTPUT: tuple of integers; zero means infinite cyclic factor
 
         EXAMPLES::
 
@@ -1043,7 +1033,7 @@ def invariants(self):
 
     def is_cyclic(self):
         """
-        Return True if the group is a cyclic group.
+        Return ``True`` if the group is a cyclic group.
 
         EXAMPLES::
 
@@ -1153,7 +1143,7 @@ def permutation_group(self):
 
     def is_commutative(self):
         """
-        Return True since this group is commutative.
+        Return ``True`` since this group is commutative.
 
         EXAMPLES::
 
@@ -1432,8 +1422,8 @@ def subgroups(self, check=False):
 
         INPUT:
 
-        - check: if ``True``, performs the same computation in GAP and
-          checks that the number of subgroups generated is the
+        - ``check`` -- boolean; if ``True``, performs the same computation in
+          GAP and checks that the number of subgroups generated is the
           same. (I don't know how to convert GAP's output back into
           Sage, so we don't actually compare the subgroups).
 
@@ -1528,15 +1518,15 @@ def subgroups(self, check=False):
 
     def subgroup_reduced(self, elts, verbose=False):
         r"""
-        Given a list of lists of integers (corresponding to elements of self),
-        find a set of independent generators for the subgroup generated by
-        these elements, and return the subgroup with these as generators,
-        forgetting the original generators.
+        Given a list of lists of integers (corresponding to elements of
+        ``self``), find a set of independent generators for the subgroup
+        generated by these elements, and return the subgroup with these as
+        generators, forgetting the original generators.
 
         This is used by the ``subgroups`` routine.
 
         An error will be raised if the elements given are not linearly
-        independent over QQ.
+        independent over `\QQ`.
 
         EXAMPLES::
 
@@ -1595,7 +1585,8 @@ def torsion_subgroup(self, n=None):
 
             sage: G = AbelianGroup([2, 2*3, 2*3*5, 0, 2*3*5*7, 2*3*5*7*11])
             sage: G.torsion_subgroup(5)                                                 # needs sage.libs.gap  # optional - gap_package_polycyclic
-            Multiplicative Abelian subgroup isomorphic to C5 x C5 x C5 generated by {f2^6, f4^42, f5^462}
+            Multiplicative Abelian subgroup isomorphic to C5 x C5 x C5
+             generated by {f2^6, f4^42, f5^462}
         """
         if n is None:
             torsion_generators = [g for g in self.gens() if g.order() != infinity]
@@ -1615,7 +1606,7 @@ def torsion_subgroup(self, n=None):
 
 class AbelianGroup_subgroup(AbelianGroup_class):
     """
-    Subgroup subclass of AbelianGroup_class, so instance methods are
+    Subgroup subclass of ``AbelianGroup_class``, so instance methods are
     inherited.
 
     .. TODO::
@@ -1787,11 +1778,9 @@ def __contains__(self, x):
 
     def ambient_group(self):
         """
-        Return the ambient group related to self.
+        Return the ambient group related to ``self``.
 
-        OUTPUT:
-
-        A multiplicative Abelian group.
+        OUTPUT: a multiplicative Abelian group
 
         EXAMPLES::
 
@@ -1809,11 +1798,11 @@ def equals(left, right):
 
         INPUT:
 
-        - ``right`` -- anything.
+        - ``right`` -- anything
 
         OUTPUT:
 
-        Boolean. If ``right`` is a subgroup, test whether ``left`` and
+        boolean; if ``right`` is a subgroup, test whether ``left`` and
         ``right`` are the same subset of the ambient group. If
         ``right`` is not a subgroup, test whether they are isomorphic
         groups, see :meth:`~AbelianGroup_class.is_isomorphic`.
@@ -1855,7 +1844,7 @@ def equals(left, right):
 
     def _repr_(self):
         """
-        Return a string representation
+        Return a string representation.
 
         EXAMPLES::
 
@@ -1879,9 +1868,7 @@ def gens(self) -> tuple:
         """
         Return the generators for this subgroup.
 
-        OUTPUT:
-
-        A tuple of group elements generating the subgroup.
+        OUTPUT: tuple of group elements generating the subgroup
 
         EXAMPLES::