Refine docstrings

src/sage/rings/function_field/function_field.py

@@ -53,11 +53,11 @@
     sage: M.base_field().base_field()
     Rational function field in x over Finite Field in a of size 5^2
 
-It is also possible to work with function fields over an imperfect base field::
+It is also possible to construct function fields over an imperfect base field::
 
     sage: N.<u> = FunctionField(K)
 
-Function field extensions can be inseparable::
+and function fields as inseparable extensions::
 
     sage: R.<v> = K[]
     sage: O.<v> = K.extension(v^5 - x)
@@ -1286,29 +1286,16 @@ def derivation(self):
         r"""
         Return a derivation of the function field over the constant base field.
 
-        If the field is a separable extension of the base field, the derivation
-        is uniquely determined from that of the base function field.
-
         A derivation on `R` is a map `R\to R` satisfying
         `D(\alpha+\beta)=D(\alpha)+D(\beta)` and `D(\alpha\beta)=\beta
-        D(\alpha)+\alpha D(\beta)` for all `\alpha, \beta \in R`. For a function
-        field which is a finite extension of `K(x)` with `K` perfect, the
-        derivations form a one-dimensional `K`-vector space generated by the
-        derivation returned by this method.
-
-        ALGORITHM:
-
-        Proposition 11 of [GT1996]_ describes how to compute the unique extension
-        of a derivation on the base function field `F` if the field is a separable
-        extension of `F`. We apply the formula described there to the generator
-        of the space of derivations on `F`.
-
-        The general inseparable case is not implemented yet (see :trac:`16562`,
-        :trac:`16564`.)`
+        D(\alpha)+\alpha D(\beta)` for all `\alpha, \beta \in R`. For a
+        function field which is a finite extension of `K(x)` with `K` perfect,
+        the derivations form a one-dimensional `K`-vector space generated by
+        the derivation returned by this method.
 
         OUTPUT:
 
-        A derivation of this function field.
+        - a derivation of the function field
 
         EXAMPLES::
 
@@ -1336,15 +1323,14 @@ def derivation(self):
             sage: d(x*y) == x*d(y) + y*d(x)
             True
 
-        Currently the functionality for finding a separable model is not
-        implemented (see :trac:`16562`, :trac:`16564`)::
+        If the field is a separable extension of the base field, the derivation
+        extending a derivation of the base function field is uniquely
+        determined. Proposition 11 of [GT1996]_ describes how to compute the
+        extension. We apply the formula described there to the generator
+        of the space of derivations on the base field.
 
-            sage: R.<y> = K[]
-            sage: L.<y> = K.extension(y^3 - x)
-            sage: L.derivation()
-            Traceback (most recent call last):
-            ...
-            NotImplementedError: construction of separable models not implemented
+        The general inseparable case is not implemented yet (see :trac:`16562`,
+        :trac:`16564`.)`
         """
         from .maps import FunctionFieldDerivation_separable
         if self.polynomial().gcd(self.polynomial().derivative()).is_one():
@@ -1962,28 +1948,24 @@ def vector_space(self, base=None):
     @cached_method
     def derivation(self):
         r"""
-        Return a generator of the space of derivations over the constant base
-        field of this function field.
-
-        A derivation on `R` is a map `R \to R` with
-        `D(\alpha + \beta) = D(\alpha) + D(\beta)` and
-        `D(\alpha \beta) = \beta D(\alpha)+\alpha D(\beta)`
-        for all `\alpha, \beta \in R`. For a function
-        field `K(x)` with `K` perfect, the derivations form a one-dimensional
-        `K`-vector space generated by the extension of the usual derivation on
-        `K[x]` (cf. Proposition 10 in [GT1996]_.)
+        Return a derivation of the rational function field over the constant
+        base field.
 
         OUTPUT:
 
-        An endofunction on this function field.
+        - a derivation of the rational function field
+
+        The derivation maps the generator of the rational function field to 1.
 
         EXAMPLES::
 
             sage: K.<x> = FunctionField(GF(3))
-            sage: K.derivation()
+            sage: m = K.derivation(); m
             Derivation map:
               From: Rational function field in x over Finite Field of size 3
               To:   Rational function field in x over Finite Field of size 3
+            sage: m(x)
+            1
 
         TESTS::
 
@@ -1992,7 +1974,6 @@ def derivation(self):
             Traceback (most recent call last):
             ...
             NotImplementedError: not implemented for non-perfect base fields
-
         """
         from .maps import FunctionFieldDerivation_rational
         if not self.constant_base_field().is_perfect():