Improve a bunch of docstrings (#662)

src/ideal/ideal.jl

@@ -82,7 +82,7 @@ end
     is_zerodim(I::sideal)
 
 Return `true` if the given ideal is zero dimensional, i.e. the Krull dimension of
-$R/I$ is zero, where $R$ is the polynomial ring over which $I$ is an ideal..
+$R/I$ is zero, where $R$ is the polynomial ring over which $I$ is an ideal.
 """
 function is_zerodim(I::sideal)
    I.isGB || error("Not a Groebner basis")
@@ -106,7 +106,7 @@ function dimension(I::sideal{spoly{T}}) where T <: Nemo.RingElem
 end
 
 @doc raw"""
-   degree(I::sideal{spoly{T}}) where T <: Nemo.RingElem
+    degree(I::sideal{spoly{T}}) where T <: Nemo.RingElem
 
 Return the (Krull) dimension and the multiplicity of the ideal generated by the
 leading monomials of the input. This is equal to the dimension and multiplicity
@@ -122,7 +122,7 @@ function degree(I::sideal{spoly{T}}) where T <: Nemo.RingElem
 end
 
 @doc raw"""
-   mult(I::sideal{spoly{T}}) where T <: Nemo.RingElem
+    mult(I::sideal{spoly{T}}) where T <: Nemo.RingElem
 
 Return the degree of the monomial ideal generated by the leading monomials of
 the input.
@@ -333,7 +333,7 @@ end
 @doc raw"""
     contains(I::sideal{S}, J::sideal{S}) where S
 
-Returns `true` if the ideal $I$ contains the ideal $J$. This will be
+Return `true` if the ideal $I$ contains the ideal $J$. This will be
 expensive if $I$ is not a Groebner ideal, since its standard basis must be
 computed.
 """
@@ -412,7 +412,7 @@ end
 @doc raw"""
     intersection(I::sideal{S}, J::sideal{S}) where {T <: Nemo.RingElem, S <: Union{spoly{T}, spluralg{T}}}
 
-Returns the intersection of the two given ideals.
+Return the intersection of the two given ideals.
 """
 function intersection(I::sideal{S}, J::sideal{S}) where {T <: Nemo.RingElem,
                                              S <: Union{spoly{T}, spluralg{T}}}
@@ -448,7 +448,7 @@ end
 @doc raw"""
     quotient(I::sideal{S}, J::sideal{S}) where S <: spoly
 
-Returns the quotient of the two given ideals. Recall that the ideal quotient
+Return the quotient of the two given ideals. Recall that the ideal quotient
 $(I:J)$ over a polynomial ring $R$ is defined by
 $\{r \in R \;|\; rJ \subseteq I\}$.
 """
@@ -462,7 +462,7 @@ end
 @doc raw"""
     quotient(I::sideal{S}, J::sideal{S}) where S <: spluralg
 
-Returns the quotient of the two given ideals, where $J$ must be two-sided.
+Return the quotient of the two given ideals, where $J$ must be two-sided.
 """
 function quotient(I::sideal{S}, J::sideal{S}) where S <: spluralg
    J.isTwoSided || error("second ideal must be two-sided")
@@ -481,7 +481,7 @@ end
 @doc raw"""
     saturation(I::sideal{T}, J::sideal{T}) where T <: Nemo.RingElem
 
-Returns the saturation of the ideal $I$ with respect to $J$, i.e. returns
+Return the saturation of the ideal $I$ with respect to $J$, i.e. returns
 the quotient ideal $(I:J^\infty)$ and the number of iterations.
 """
 function saturation(I::sideal{T}, J::sideal{T}) where T <: Nemo.RingElem
@@ -822,7 +822,7 @@ end
 @doc raw"""
     lift_std_syz(M::sideal{S}; complete_reduction::Bool = false) where S <: spoly
 
-computes the Groebner base G of I, the transformation matrix T and the syzygies of M.
+Computes the Groebner base G of I, the transformation matrix T and the syzygies of M.
 Returns G,T,S
 (Matrix(G) = Matrix(I) * T, 0=Matrix(M)*Matrix(S))
 """
@@ -835,7 +835,7 @@ end
 @doc raw"""
     lift_std(M::sideal{S}; complete_reduction::Bool = false) where S <: spoly
 
-computes the Groebner base G of M and the transformation matrix T such that
+Computes the Groebner base G of M and the transformation matrix T such that
 (Matrix(G) = Matrix(M) * T)
 """
 function lift_std(M::sideal{S}; complete_reduction::Bool = false) where S <: spoly
@@ -851,8 +851,9 @@ end
 ###############################################################################
 
 @doc raw"""
-     fres{T <: Nemo.FieldElem}(id::Union{sideal{spoly{T}}, smodule{spoly{T}}},
-      max_length::Int, method::String="complete")
+    fres(id::Union{sideal{spoly{T}}, smodule{spoly{T}}},
+      max_length::Int, method::String="complete") where T <: Nemo.FieldElem
+
 Compute a free resolution of the given ideal/module up to the maximum given
 length. The ideal/module must be over a polynomial ring over a field, and
 a Groebner basis.
@@ -881,7 +882,8 @@ function fres(id::Union{sideal{spoly{T}}, smodule{spoly{T}}}, max_length::Int, m
 end
 
 @doc raw"""
-     sres{T <: Nemo.FieldElem}(id::sideal{spoly{T}}, max_length::Int)
+    sres(id::sideal{spoly{T}}, max_length::Int) where T <: Nemo.FieldElem
+
 Compute a (free) Schreyer resolution of the given ideal up to the maximum
 given length. The ideal must be over a polynomial ring over a field, and a
 Groebner basis. The result is given as a resolution, whose i-th entry is
@@ -1075,7 +1077,7 @@ end
 @doc raw"""
     independent_sets(I::sideal{spoly{T}}) where T <: Nemo.FieldElem
 
-Returns all non-extendable independent sets of $lead(I)$. $I$ has to be given
+Return all non-extendable independent sets of $lead(I)$. $I$ has to be given
 by a Groebner basis.
 """
 function independent_sets(I::sideal{spoly{T}}) where T <: Nemo.FieldElem

src/libsingular/ideals.jl

@@ -6,7 +6,7 @@ end
    preimage_ptr = icxx"""
       sip_smap sing_map = { $map->m, (char *)"julia_ring", 1, $map->ncols };
       return maGetPreimage($target, &sing_map, $id, $source);
-   """
-   return preimage_ptr;
+   @doc raw"""
+    return preimage_ptr;
 end
- =#
+ =#

src/map/alghom.jl

@@ -61,7 +61,7 @@ end
     compose(f::AbstractAlgebra.Map(Singular.SAlgHom),
                          g::AbstractAlgebra.Map(Singular.SAlgHom))
 
-Returns an algebra homomorphism $h: domain(f) \to codomain(g)$,
+Return an algebra homomorphism $h: domain(f) \to codomain(g)$,
 where $h = g(f)$.
 """
 function compose(f::Map(SAlgHom), g::Map(SAlgHom))
@@ -97,7 +97,7 @@ end
 @doc raw"""
     preimage(f::AbstractAlgebra.Map(SAlgHom), I::sideal)
 
-Returns the preimage of the ideal $I$ under the algebra homomorphism $f$.
+Return the preimage of the ideal $I$ under the algebra homomorphism $f$.
 """
 function preimage(f::Map(SAlgHom), I::sideal)
 
@@ -118,7 +118,7 @@ end
 @doc raw"""
     kernel(f::AbstractAlgebra.Map(SAlgHom))
 
-Returns the kernel of the algebra homomorphism $f$.
+Return the kernel of the algebra homomorphism $f$.
 """
 function kernel(f::Map(SAlgHom))
    return preimage(f, Ideal(f.codomain, ))

src/map/idalghom.jl

@@ -90,7 +90,7 @@ end
 @doc raw"""
     preimage(f::AbstractAlgebra.Map(SIdAlgHom), I::sideal)
 
-Returns the preimage of the ideal $I$ under the identity algebra homomorphism.
+Return the preimage of the ideal $I$ under the identity algebra homomorphism.
 """
 function preimage(f::Map(SIdAlgHom), I::sideal)
 
@@ -104,7 +104,7 @@ end
 @doc raw"""
     kernel(f::AbstractAlgebra.Map(SIdAlgHom))
 
-Returns the kernel of the identity algebra homomorphism.
+Return the kernel of the identity algebra homomorphism.
 """
 function kernel(f::Map(SIdAlgHom))
    return Ideal(f.domain, )

src/module/module.jl

@@ -145,7 +145,7 @@ end
 Given a module $I$ this function computes a Groebner basis for it.
 Compared to `std`, `slimgb` uses different strategies for choosing
 a reducer.
->
+
 If the optional parameter `complete_reduction` is set to `true` the
 function computes a reduced Gröbner basis for $I$.
 """
@@ -165,7 +165,8 @@ end
 ###############################################################################
 
 @doc raw"""
-   reduce(M::smodule, G::smodule)
+    reduce(M::smodule, G::smodule)
+
 Return a submodule whose generators are the generators of $M$ reduced by the
 submodule $G$. The submodule $G$ need not be a Groebner basis. The returned
 submodule will have the same number of generators as $M$, even if they are zero.
@@ -221,7 +222,7 @@ end
 ###############################################################################
 
 @doc raw"""
-    sres{T <: Singular.FieldElem}(I::smodule{spoly{T}}, max_length::Int)
+    sres(I::smodule{spoly{T}}, max_length::Int) where T <: Singular.FieldElem
 
 Compute a free resolution of the given module $I$ of length up to the given
 maximum length. If `max_length` is set to zero, a full length free
@@ -261,7 +262,8 @@ end
 ###############################################################################
 
 @doc raw"""
-   jet(M::smodule, n::Int)
+    jet(M::smodule, n::Int)
+
 Given a module $M$ this function truncates the generators of $M$
 up to degree $n$.
 """
@@ -279,9 +281,9 @@ end
 ###############################################################################
 
 @doc raw"""
-   minimal_generating_set(M::smodule)
-Given a module $M$ in ring $R$ with local ordering, this returns an array
-containing the minimal generators of $M$.
+    minimal_generating_set(M::smodule)
+
+Return a vector containing the minimal generators of $M$.
 """
 function minimal_generating_set(M::smodule)
    R = base_ring(M)
@@ -302,9 +304,8 @@ end
 @doc raw"""
     eliminate(M::smodule, polys::spoly...)
 
-Given a list of polynomials which are variables, construct the
-the intersection of M with the free module
-where those variables have been eliminated.
+Given a module `M` and a list of polynomials which are variables, construct the
+intersection of `M` with the free module where those variables have been eliminated.
 """
 function eliminate(M::smodule, polys::spoly...)
    R = base_ring(M)
@@ -379,9 +380,8 @@ end
 @doc raw"""
     lift_std_syz(M::smodule)
 
-computes the Groebner base G of M, the transformation matrix T and the syzygies of M.
-Returns G,T,S
-(Matrix(G) = Matrix(M) * T, 0=Matrix(M)*Matrix(S))
+Computes the Groebner base `G` of `M`, the transformation matrix `T` and the syzygies of M.
+Returns a tuple `(G,T,S)` satisfying `(Matrix(G) = Matrix(M) * T, 0=Matrix(M)*Matrix(S))`.
 """
 function lift_std_syz(M::smodule; complete_reduction::Bool = false)
    R = base_ring(M)
@@ -392,8 +392,8 @@ end
 @doc raw"""
     lift_std(M::smodule)
 
-computes the Groebner base G of M and the transformation matrix T such that
-(Matrix(G) = Matrix(M) * T)
+Computes the Groebner base `G` of `M` and the transformation matrix `T` such that
+`(Matrix(G) = Matrix(M) * T)`.
 """
 function lift_std(M::smodule; complete_reduction::Bool = false)
    R = base_ring(M)
@@ -410,7 +410,7 @@ end
 @doc raw"""
     modulo(A::smodule, B:smodule)
 
-represents  A/(A intersect B) (isomorphic to (A+B)/B)
+Represents  A/(A intersect B) (isomorphic to (A+B)/B)
 """
 function modulo(A::smodule, B::smodule)
    R = base_ring(A)

src/number/n_GF.jl

@@ -334,7 +334,7 @@ promote_rule(C::Type{n_GF}, ::Type{n_Z}) = n_GF
 @doc raw"""
     FiniteField(p::Int, n::Int, S::VarName; cached=true)
 
-Returns a tuple `K, a` consisting of a finite field `K` of characteristic $p$
+Return a tuple `K, a` consisting of a finite field `K` of characteristic $p$
 and degree $n$, and its generator `a`. The string used to print the
 generator is given by `S`. If the finite field is not listed in the Conway
 tables included in Singular, an error will be raised. By default, finite

src/number/n_transExt.jl

@@ -121,7 +121,7 @@ end
 @doc raw"""
     n_transExt_to_spoly(x::n_transExt; parent::PolyRing)
 
-Returns the numerator of `x` as a polynomial in a polynomial ring with at least
+Return the numerator of `x` as a polynomial in a polynomial ring with at least
 as many variables as the transcendence degree of `parent(x)`. If a ring `parent`
 is given to the function, it will be the parent ring of the output.
 """
@@ -374,7 +374,7 @@ end
 @doc raw"""
     FunctionField(F::Singular.Field, S::AbstractVector{<:VarName})
 
-Returns a tuple $K, a$ consisting of a function field $K$ over the field $F$
+Return a tuple $K, a$ consisting of a function field $K$ over the field $F$
 with transcendence basis stored in the array $S$.
 """
 function FunctionField(F::Singular.Field, S::AbstractVector{<:VarName}; cached::Bool=true)
@@ -388,7 +388,7 @@ end
 @doc raw"""
     FunctionField(F::Singular.Field, n::Int)
 
-Returns a tuple $K, a$ consisting of a function field $K$ over the field $F$
+Return a tuple $K, a$ consisting of a function field $K$ over the field $F$
 with transcendence degree $n$ and transcendence basis $a1, ..., an$.
 """
 function FunctionField(F::Singular.Field, n::Int; cached::Bool=true)

src/poly/poly.jl

@@ -232,7 +232,7 @@ end
 @doc raw"""
     order(p::spoly)
 
-Returns the order of $p$.
+Return the order of $p$.
 """
 function order(p::spoly)
    if p.ptr.cpp_object == C_NULL
@@ -1287,7 +1287,7 @@ end
 @doc raw"""
     jacobian_ideal(p::spoly{T}) where T <: Nemo.RingElem
 
-Returns the ideal generated by all partial derivatives of $x$.
+Return the ideal generated by all partial derivatives of $x$.
 """
 function jacobian_ideal(p::spoly{T}) where T <: Nemo.RingElem
    R = parent(p)
@@ -1298,7 +1298,7 @@ end
 @doc raw"""
     jacobian_matrix(p::spoly{T}) where T <: Nemo.RingElem
 
-Returns the column matrix $\{\frac{\partial p}{\partial x_i}\}_i$ of partial derivatives.
+Return the column matrix $\{\frac{\partial p}{\partial x_i}\}_i$ of partial derivatives.
 """
 function jacobian_matrix(p::spoly{T}) where T <: Nemo.RingElem
    R = parent(p)
@@ -1313,7 +1313,7 @@ end
 @doc raw"""
     jacobian_matrix(a::Vector{spoly{T}}) where T <: Nemo.RingElem
 
-Returns the matrix $\{\frac{\partial a_i}{\partial x_j}\}_{ij}$ of partial derivatives.
+Return the matrix $\{\frac{\partial a_i}{\partial x_j}\}_{ij}$ of partial derivatives.
 """
 function jacobian_matrix(A::Vector{spoly{T}}) where T <: Nemo.RingElem
    m = length(A)