18290: proofreading

src/sage/categories/additive_magmas.py

@@ -762,7 +762,7 @@ def is_empty(self):
                 Return whether this set is empty.
 
                 Since this set is an additive magma it has a zero element and
-                hence is not empty. This method always return ``False``.
+                hence is not empty. This method thus always returns ``False``.
 
                 EXAMPLES::
 

src/sage/categories/enumerated_sets.py

@@ -324,7 +324,7 @@ def _unrank_from_iterator(self, r):
             """
             The ``r``-th element of ``self``
 
-            ``self.unrank(r)`` returns the ``r``-th element of self where
+            ``self.unrank(r)`` returns the ``r``-th element of self, where
             ``r`` is an integer between ``0`` and ``n-1`` where ``n`` is the
             cardinality of ``self``.
 
@@ -716,8 +716,8 @@ class CartesianProducts(CartesianProductsCategory):
 
         class ParentMethods:
             def __iter__(self):
-                """
-                Return an iterator for the elements of this cartesian product
+                r"""
+                Return an iterator for the elements of this cartesian product.
 
                 EXAMPLES::
 
@@ -751,18 +751,30 @@ def __iter__(self):
                      [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
                      [1, 2, 3, 4, 5, 6, 7, 8, 10, 9])
 
-                    sage: it = iter(cartesian_product([ZZ,GF(5)]))
-                    sage: it.next()
-                    Traceback (most recent call last):
-                    ...
-                    ValueError: the iteration order of cartesian product of
-                    infinite sets is not well defined
+                .. WARNING::
+
+                    The elements are returned in lexicographic order,
+                    which gives a valid enumeration only in the finite
+                    case::
+
+                        sage: it = iter(cartesian_product([ZZ,GF(5)]))
+                        sage: it.next()
+                        Traceback (most recent call last):
+                        ...
+                        ValueError: the iteration order of cartesian product of
+                        infinite sets is not well defined
+
 
                 .. NOTE::
 
-                    Here it would be faster to use ``itertools.factor`` for sets
+                    Here it would be faster to use :meth:`itertools.product` for sets
                     of small size. But the latter expands all factor in memory!
                     So we can not reasonably use it in general.
+
+                ALGORITHM:
+
+                Recipe 19.9 in the Python Cookbook by Alex Martelli
+                and David Ascher.
                 """
                 if not self.is_finite():
                     raise ValueError("the iteration order of cartesian product of infinite sets is not well defined")

src/sage/categories/finite_enumerated_sets.py

@@ -484,33 +484,37 @@ def extra_super_categories(self):
             return [FiniteEnumeratedSets()]
 
         class ParentMethods:
-            # NOTE: three methods are overriden to avoid the default
-            # implementations in FiniteEnumeratedSets
+            # Ambiguity resolution between methods inherited from
+            # Sets.CartesianProducts and from EnumeratedSets.Finite.
             random_element = Sets.CartesianProducts.ParentMethods.random_element.im_func
             r"""
-            Return a random element
+            Return a random element.
 
             TESTS:
 
-            We check that parents inherit the right function::
+            We check that cartesian products of finite enumerated sets
+            inherit the `random` method from `Sets.CartesianProducts`
+            and not from :class:`EnumeratedSets.Finite`::
 
                 sage: C = cartesian_product([Permutations(10), Permutations(10)])
-                sage: C in FiniteEnumeratedSets()
+                sage: C in EnumeratedSets().Finite()
                 True
                 sage: C.random_element.__module__
                 'sage.categories.sets_cat'
             """
 
             cardinality = Sets.CartesianProducts.ParentMethods.cardinality.im_func
             r"""
-            Return the cardinality
+            Return the cardinality.
 
             TESTS:
 
-            We check that parents inherit the right function::
+            We check that cartesian products of finite enumerated sets
+            inherit the `cardinality` method from `Sets.CartesianProducts`
+            and not from :class:`EnumeratedSets.Finite`::
 
                 sage: C = cartesian_product([Partitions(10), Permutations(12)])
-                sage: C in FiniteEnumeratedSets()
+                sage: C in EnumeratedSets().Finite()
                 True
                 sage: C.cardinality.__module__
                 'sage.categories.sets_cat'
@@ -522,10 +526,12 @@ class ParentMethods:
 
             TESTS:
 
-            We check parents inherit the right function::
+            We check that cartesian products of finite enumerated sets
+            inherit the `__iter__` method from `Sets.CartesianProducts`
+            and not from :class:`EnumeratedSets.Finite`::
 
                 sage: C = cartesian_product([Partitions(10), Permutations(12)])
-                sage: C in FiniteEnumeratedSets()
+                sage: C in EnumeratedSets().Finite()
                 True
                 sage: C.__iter__.__module__
                 'sage.categories.enumerated_sets'
@@ -546,11 +552,16 @@ def last(self):
 
             def rank(self, x):
                 r"""
-                The rank of an element of this cartesian product
+                Return the rank of an element of this cartesian product.
 
-                The *rank* of ``x`` is its position in the enumeration.  It is
-                an integer between ``0`` and ``n-1`` where ``n`` is the
-                cardinality of this set.
+                The *rank* of ``x`` is its position in the
+                enumeration. It is an integer between ``0`` and
+                ``n-1`` where ``n`` is the cardinality of this set.
+
+                .. SEEALSO::
+
+                    - :meth:`EnumeratedSets.ParentMethods.rank`
+                    - :meth:`unrank`
 
                 EXAMPLES::
 
@@ -588,19 +599,24 @@ def rank(self, x):
                 b = ZZ.one()
                 rank = ZZ.zero()
                 for f,c in itertools.izip(reversed(x.cartesian_factors()),
-                                      reversed(self.cartesian_factors())):
+                                          reversed(self.cartesian_factors())):
                     rank += b * c.rank(f)
                     b *= c.cardinality()
                 return rank
 
             def unrank(self, i):
                 r"""
-                The ``i``-th element of this cartesian product
+                Return the ``i``-th element of this cartesian product.
 
                 INPUT:
 
-                - ``i`` -- integer between ``0`` and ``n-1`` where ``n`` is the
-                  cardinality of this set.
+                - ``i`` -- integer between ``0`` and ``n-1`` where
+                  ``n`` is the cardinality of this set.
+
+                .. SEEALSO::
+
+                    - :meth:`EnumeratedSets.ParentMethods.unrank`
+                    - :meth:`rank`
 
                 EXAMPLES::
 

src/sage/categories/finite_groups.py

@@ -211,6 +211,3 @@ def extra_super_categories(self):
                 return [Algebras(self.base_ring()).Semisimple()]
             else:
                 return []
-
-
-

src/sage/categories/sets_cat.py

@@ -1682,7 +1682,9 @@ class ParentMethods:
 
             def is_finite(self):
                 """
-                Return ``False`` since ``self`` is not finite.
+                Return whether this set is finite.
+
+                Since this set is infinite this always returns ``False``.
 
                 EXAMPLES::
 
@@ -1699,9 +1701,9 @@ def is_finite(self):
 
             def is_empty(self):
                 r"""
-                Test whether this set is empty.
+                Return whether this set is empty.
 
-                Since this set is infinite it is not empty.
+                Since this set is infinite this always returns ``False``.
 
                 EXAMPLES::
 
@@ -2021,7 +2023,7 @@ def an_element(self):
 
             def is_empty(self):
                 r"""
-                Test whether this set is empty.
+                Return whether this set is empty.
 
                 EXAMPLES::
 
@@ -2037,7 +2039,7 @@ def is_empty(self):
 
             def is_finite(self):
                 r"""
-                Test whether this set is finite.
+                Return whether this set is finite.
 
                 EXAMPLES::
 
@@ -2094,8 +2096,8 @@ def random_element(self, *args):
                 r"""
                 Return a random element of this cartesian product.
 
-                The extra arguments are sent to each of the factor of the
-                cartesian product.
+                The extra arguments are passed down to each of the
+                factors of the cartesian product.
 
                 EXAMPLES::