Some reviewer tweaks and doc additions.

Author: Travis Scrimshaw

src/sage/categories/modules.py

@@ -405,7 +405,10 @@ def Super(self, base_ring=None):
 
             .. TODO::
 
-                Same as :meth:`Graded`.
+                - Explain why this does not commute with :meth:`WithBasis`
+                - Improve the support for covariant functorial
+                  constructions categories over a base ring so as to
+                  get rid of the ``base_ring`` argument.
 
             TESTS::
 
@@ -476,7 +479,11 @@ def tensor_square(self):
 
                 sage: A = HopfAlgebrasWithBasis(QQ).example()
                 sage: A.tensor_square()
-                An example of Hopf algebra with basis: the group algebra of the Dihedral group of order 6 as a permutation group over Rational Field # An example of Hopf algebra with basis: the group algebra of the Dihedral group of order 6 as a permutation group over Rational Field
+                An example of Hopf algebra with basis:
+                 the group algebra of the Dihedral group of order 6
+                 as a permutation group over Rational Field # An example
+                 of Hopf algebra with basis: the group algebra of the Dihedral
+                 group of order 6 as a permutation group over Rational Field
             """
             return tensor([self, self])
 

src/sage/categories/super_algebras.py

@@ -17,6 +17,18 @@ class SuperAlgebras(SuperModulesCategory):
     """
     The category of super algebras.
 
+    An `R`-*super algebra* is an `R`-super module `A` endowed with an
+    `R`-algebra structure satisfying
+
+    .. MATH::
+
+        A_0 A_0 \subseteq A_0, \qquad
+        A_0 A_1 \subseteq A_1, \qquad
+        A_1 A_0 \subseteq A_1, \qquad
+        A_1 A_1 \subseteq A_0
+
+    and `1 \in A_0`.
+
     EXAMPLES::
 
         sage: Algebras(ZZ).Super()

src/sage/categories/super_hopf_algebras_with_basis.py

@@ -12,7 +12,7 @@
 
 class SuperHopfAlgebrasWithBasis(SuperModulesCategory):
     """
-    The category of super algebras with a distinguished basis
+    The category of super Hopf algebras with a distinguished basis.
 
     EXAMPLES::
 

src/sage/categories/super_modules.py

@@ -16,6 +16,8 @@
 from sage.categories.covariant_functorial_construction import CovariantConstructionCategory
 from sage.categories.modules import Modules
 
+# Note, a commutative algebra is not a commutative super algebra,
+#   therefore the following whitelist.
 axiom_whitelist = frozenset(["Facade", "Finite", "Infinite",
                              "FiniteDimensional", "Connected", "WithBasis",
                              # "Commutative",
@@ -88,6 +90,15 @@ class SuperModules(SuperModulesCategory):
     """
     The category of super modules.
 
+    An `R`-*super module* (where `R` is a ring) is an `R`-module `M` equipped
+    with a decomposition `M = M_0 \oplus M_1` into two `R`-submodules
+    `M_0` and `M_1` (called the *even part* and the *odd part* of `M`,
+    respectively).
+
+    Thus, an `R`-super module automatically becomes a `\ZZ / 2 \ZZ`-graded
+    `R`-module, with `M_0` being the degree-`0` component and `M_1` being the
+    degree-`1` component.
+
     EXAMPLES::
 
         sage: Modules(ZZ).Super()
@@ -134,7 +145,7 @@ def extra_super_categories(self):
             []
 
         This makes sure that ``Modules(QQ).Super()`` returns an
-        instance of :class:`GradedModules` and not a join category of
+        instance of :class:`SuperModules` and not a join category of
         an instance of this class and of ``VectorSpaces(QQ)``::
 
             sage: type(Modules(QQ).Super())
@@ -144,7 +155,7 @@ def extra_super_categories(self):
 
             Get rid of this workaround once there is a more systematic
             approach for the alias ``Modules(QQ)`` -> ``VectorSpaces(QQ)``.
-            Probably the later should be a category with axiom, and
+            Probably the latter should be a category with axiom, and
             covariant constructions should play well with axioms.
         """
         from sage.categories.modules import Modules
@@ -164,6 +175,14 @@ def is_even_odd(self):
             Return ``0`` if ``self`` is an even element or ``1``
             if an odd element.
 
+            .. NOTE::
+
+                The default implementation assumes that the even/odd is
+                determined by the parity of :meth:`degree`.
+
+                Overwrite this method if the even/odd behavior is desired
+                to be independent.
+
             EXAMPLES::
 
                 sage: cat = Algebras(QQ).WithBasis().Super()

src/sage/categories/super_modules_with_basis.py

@@ -14,6 +14,10 @@ class SuperModulesWithBasis(SuperModulesCategory):
     """
     The category of super modules with a distinguished basis.
 
+    An `R`-*super module with a distinguished basis* is an
+    `R`-super module equipped with an `R`-module basis whose elements are
+    homogeneous.
+
     EXAMPLES::
 
         sage: C = GradedModulesWithBasis(ZZ); C
@@ -31,13 +35,21 @@ class SuperModulesWithBasis(SuperModulesCategory):
     class ParentMethods:
         def _even_odd_on_basis(self, m):
             """
-            Return if ``m`` is an index of an even or odd basis element.
+            Return the parity of the basis element indexed by ``m``.
 
             OUTPUT:
 
             ``0`` if ``m`` is for an even element or ``1`` if ``m``
             is for an odd element.
 
+            .. NOTE::
+
+                The default implementation assumes that the even/odd is
+                determined by the parity of :meth:`degree`.
+
+                Overwrite this method if the even/odd behavior is desired
+                to be independent.
+
             EXAMPLES::
 
                 sage: Q = QuadraticForm(QQ, 2, [1,2,3])
@@ -53,7 +65,7 @@ class ElementMethods:
         def is_super_homogeneous(self):
             r"""
             Return whether this element is homogeneous, in the sense
-            of a super module.
+            of a super module (i.e., is even or odd).
 
             EXAMPLES::
 
@@ -70,8 +82,8 @@ def is_super_homogeneous(self):
                 False
 
             The exterior algebra has a `\ZZ` grading, which induces the
-            `\ZZ / 2\ZZ` grading, however the definition of homogeneous
-            elements differ because of the different gradings::
+            `\ZZ / 2\ZZ` grading. However the definition of homogeneous
+            elements differs because of the different gradings::
 
                 sage: E.<x,y> = ExteriorAlgebra(QQ)
                 sage: a = x*y + 4