More documentation

src/sage/modules/free_module.py

@@ -268,7 +268,7 @@ def create_object(self, version, key):
 
 def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_matrix=None, *,
                with_basis='standard', rank=None, basis_keys=None, **args):
-    """
+    r"""
     Create a free module over the given commutative ``base_ring``
 
     ``FreeModule`` can be called with the following positional arguments:
@@ -298,10 +298,50 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m
 
     OUTPUT: a free module
 
-    .. note::
+    This factory function creates instances of various specialized classes
+    depending on the input.  Not all combinations of options are
+    implemented.
+
+    -  If the parameter ``basis_keys`` is provided, it must be a finite
+       or enumerated family of objects, and an instance of
+       :class:`CombinatorialFreeModule` is created.
+
+       EXAMPLE::
+
+           sage: CombinatorialFreeModule(QQ, ['a','b','c'])
+           Free module generated by {'a', 'b', 'c'} over Rational Field
+
+       It has a distinguished standard basis that is indexed by the provided
+       ``basis_keys``. See the documentation of :class:`CombinatorialFreeModule`
+       for more examples and details, including its :class:`UniqueRepresentation`
+       semantics.
+
+    -  If the parameter ``with_basis`` is set to ``None``, then a free module
+       of the given ``rank`` without distinguished basis is created.  It is
+       represented by an instance of :class:`FiniteRankFreeModule`.
+
+       EXAMPLE::
+
+           sage: FiniteRankFreeModule(ZZ, 3, name='M')
+           Rank-3 free module M over the Integer Ring
+
+       See the documentation of :class:`FiniteRankFreeModule` for more
+       options, examples, and details.
+
+    -  If ``rank`` is provided and the option ``with_basis`` is left at its
+       default value, ``"standard"``, then a free ambient module with
+       distinguished standard basis indexed by ``range(rank)`` is created.
+       There is only one dense and one sparse free ambient module of
+       given ``rank`` over ``base_ring``.
+
+       EXAMPLE::
+
+           sage: FreeModule(Integers(8), 10)
+           Ambient free module of rank 10 over Ring of integers modulo 8
+
+       The remainder of this documentation discusses this case of
+       free ambient modules.
 
-       In Sage it is the case that there is only one dense and one
-       sparse free ambient module of rank `n` over `R`.
 
     EXAMPLES:
 
@@ -314,8 +354,6 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m
 
     ::
 
-        sage: FreeModule(Integers(8),10)
-        Ambient free module of rank 10 over Ring of integers modulo 8
         sage: FreeModule(QQ,10)
         Vector space of dimension 10 over Rational Field
         sage: FreeModule(ZZ,10)