Trac 10963: added mathematical definitions to the documentation of a …

…bunch of axioms

src/sage/categories/additive_magmas.py

@@ -73,6 +73,13 @@ def AdditiveAssociative(self):
             """
             Return the full subcategory of the additive associative objects of ``self``.
 
+            An :class:`additive magma AdditiveMagmas` `M` is
+            *associative* if, for all `x,y,z\in M`,
+
+            .. MATH:: x + (y + z) = (x + y) + z
+
+            .. SEEALSO:: :wikipedia:`Associative_property`.
+
             EXAMPLES::
 
                 sage: AdditiveMagmas().AdditiveAssociative()
@@ -91,6 +98,13 @@ def AdditiveCommutative(self):
             """
             Return the full subcategory of the commutative objects of ``self``.
 
+            An :class:`additive magma AdditiveMagmas` `M` is
+            *commutative* if, for all `x,y\in M`,
+
+            .. MATH:: x + y = y + x
+
+            .. SEEALSO:: :wikipedia:`Commutative_property`.
+
             EXAMPLES::
 
                 sage: AdditiveMagmas().AdditiveCommutative()
@@ -113,6 +127,17 @@ def AdditiveUnital(self):
             r"""
             Return the subcategory of the unital objects of ``self``.
 
+            An :class:`additive magma AdditiveMagmas` `M` is *unital*
+            if it admits an element `0`, called *neutral element*,
+            such that for all `x\in M`,
+
+            .. MATH:: 0 + x = x + 0 = x
+
+            This element is necessarily unique, and should be provided
+            as ``M.zero()``.
+
+            .. SEEALSO:: :wikipedia:`Unital_magma#unital`
+
             EXAMPLES::
 
                 sage: AdditiveMagmas().AdditiveUnital()

src/sage/categories/magmas.py

@@ -72,6 +72,13 @@ def Associative(self):
             """
             Return the full subcategory of the associative objects of ``self``.
 
+            A (multiplicative) :class:`magma Magmas` `M` is
+            *associative* if, for all `x,y,z\in M`,
+
+            .. MATH:: x * (y * z) = (x * y) * z
+
+            .. SEEALSO:: :wikipedia:`Associative_property`.
+
             EXAMPLES::
 
                 sage: Magmas().Associative()
@@ -90,6 +97,13 @@ def Commutative(self):
             """
             Return the full subcategory of the commutative objects of ``self``.
 
+            A (multiplicative) :class:`magma Magmas` `M` is
+            *commutative* if, for all `x,y\in M`,
+
+            .. MATH:: x * y = y * x
+
+            .. SEEALSO:: :wikipedia:`Commutative_property`.
+
             EXAMPLES::
 
                 sage: Magmas().Commutative()
@@ -110,6 +124,17 @@ def Unital(self):
             r"""
             Return the subcategory of the unital objects of ``self``.
 
+            A (multiplicative) :class:`magma Magmas` `M` is *unital*
+            if it admits an element `1`, called *unit*, such that for
+            all `x\in M`,
+
+            .. MATH:: 1 * x = x * 1 = x
+
+            This element is necessarily unique, and should be provided
+            as ``M.one()``.
+
+            .. SEEALSO:: :wikipedia:`Unital_magma#unital`
+
             EXAMPLES::
 
                 sage: Magmas().Unital()
@@ -139,16 +164,17 @@ def Distributive(self):
 
             - ``self`` -- a subcategory of :class:`Magmas` and :class:`AdditiveMagmas`
 
-            Given that Sage does not know that
+            Given that `Sage` does not yet know that the category
             :class:`MagmasAndAdditiveMagmas` is the intersection of
-            :class:`Magmas` and :class:`AdditiveMagmas`, the method
+            the categories :class:`Magmas` and
+            :class:`AdditiveMagmas`, the method
             :meth:`MagmasAndAdditiveMagmas.SubcategoryMethods.Distributive`
             is not available, as would be desirable, for this intersection.
 
-            As a workaround, this method checks that ``self`` is a
-            subcategory of both :class:`Magmas`() and
-            :class:`AdditiveMagmas`() and upgrades it to a subcategory
-            of :class:`MagmasAndAdditiveMagmas`() before applying the
+            This method is a workaround. It checks that ``self`` is a
+            subcategory of both :class:`Magmas` and
+            :class:`AdditiveMagmas` and upgrades it to a subcategory
+            of :class:`MagmasAndAdditiveMagmas` before applying the
             axiom. It complains overwise, since the ``Distributive``
             axiom does not make sense for a plain magma.
 

src/sage/categories/magmas_and_additive_magmas.py

@@ -57,29 +57,38 @@ def Distributive(self):
             """
             Return the full subcategory of the objects of ``self`` where `*` is distributive on `+`.
 
+            A :class:`magma Magmas` and :class:`additive magma
+            AdditiveMagmas` `M` is *distributive* if, for all
+            `x,y,z\in M`,
+
+            .. MATH:: x * (y+z) = x*y + x*z \text{ and } (x+y) * z = x*z + y*z
+
             EXAMPLES::
 
                 sage: from sage.categories.magmas_and_additive_magmas import MagmasAndAdditiveMagmas
-                sage: C = MagmasAndAdditiveMagmas().Distributive()
+                sage: C = MagmasAndAdditiveMagmas().Distributive(); C
+                Category of distributive magmas and additive magmas
 
-            Given that `Sage` does not know that
-            :class:`MagmasAndAdditiveMagmas` is the intersection of
-            :class:`Magmas` and :class:`AdditiveMagmas`, this method
-            is not available for
+            .. NOTE::
 
-                sage: Magmas() & AdditiveMagmas()
-                Join of Category of magmas and Category of additive magmas
+                Given that `Sage` does not know that
+                :class:`MagmasAndAdditiveMagmas` is the intersection
+                of :class:`Magmas` and :class:`AdditiveMagmas`, this
+                method is not available for::
 
-            Still, the natural syntax works::
+                    sage: Magmas() & AdditiveMagmas()
+                    Join of Category of magmas and Category of additive magmas
 
-                sage: (Magmas() & AdditiveMagmas()).Distributive()
-                Category of distributive magmas and additive magmas
+                Still, the natural syntax works::
+
+                    sage: (Magmas() & AdditiveMagmas()).Distributive()
+                    Category of distributive magmas and additive magmas
 
-            thanks to a workaround implemented in
-            :meth:`Magmas.SubcategoryMethods.Distributive`::
+                thanks to a workaround implemented in
+                :meth:`Magmas.SubcategoryMethods.Distributive`::
 
-                sage: (Magmas() & AdditiveMagmas()).Distributive.__module__
-                'sage.categories.magmas'
+                    sage: (Magmas() & AdditiveMagmas()).Distributive.__module__
+                    'sage.categories.magmas'
 
             TESTS::
 

src/sage/categories/rings.py

@@ -57,21 +57,28 @@ class Rings(CategoryWithAxiom):
     class SubcategoryMethods:
 
         def NoZeroDivisors(self):
-            """
-            Return the full subcategory of the objects of ``self`` having no zero divisors.
+            """Return the full subcategory of the objects of ``self`` having no nonzero zero divisors.
+
+            A *zero divisor* in a ring `R` is an element `x\in R` such
+            that there exists a nonzero element `y\in R` such that
+            `x*y=0` or `y*x=0` (see :wikipedia:`Zero_divisor`).
 
             EXAMPLES::
 
                 sage: Rings().NoZeroDivisors()
                 Category of domains
 
-            .. NOTE:: this could be generalized to MagmasAndAdditiveMagmas.Distributive.AdditiveUnital
+            .. NOTE::
+
+                This could be generalized to
+                :class:`MagmasAndAdditiveMagmas.Distributive.AdditiveUnital`.
 
             TESTS::
 
                 sage: TestSuite(Rings().NoZeroDivisors()).run()
                 sage: Algebras(QQ).NoZeroDivisors.__module__
                 'sage.categories.rings'
+
             """
             return self._with_axiom('NoZeroDivisors')
 
@@ -82,7 +89,10 @@ def Division(self):
             A ring satisfies the *division axiom* if all non-zero
             elements have multiplicative inverses.
 
-            .. NOTE:: this could be generalized to MagmasAndAdditiveMagmas.Distributive.AdditiveUnital.Unital
+            .. NOTE::
+
+                This could be generalized to
+                :class:`MagmasAndAdditiveMagmas.Distributive.AdditiveUnital`.
 
             EXAMPLES::