Document (m)poly_type, (m)poly_ring_type in the manual (#2314)

Author: JohnAAbbott

docs/src/mpoly_interface.md

@@ -48,14 +48,31 @@ Note that both abstract types are parameterised. The type `T` should usually be
 of elements of the coefficient ring of the polynomial ring. For example, in the case of
 $\mathbb{Z}[x, y]$ the type `T` would be the type of an integer, e.g. `BigInt`.
 
+Given a type for the coefficients, we can obtain the corresponding type of a
+multivariate polynomial having that type of coefficient:
+
+```@docs
+mpoly_type
+```
+
+Analogously, given a type for the coefficients, we can obtain the corresponding
+type of the ring of multivariate polynomials having that type of coefficient:
+
+```@docs
+mpoly_ring_type
+```
+
+### Identical polynomial rings
+
 Multivariate polynomial rings should be made unique on the system by caching parent
 objects (unless an optional `cache` parameter is set to `false`). Multivariate
 polynomial rings should at least be distinguished based on their base (coefficient)
 ring and number of variables. But if they have the same base ring, symbols (for their
 variables/generators) and ordering, they should certainly have the same parent object.
 
-See `src/generic/GenericTypes.jl` for an example of how to implement such a cache (which
-usually makes use of a dictionary).
+Implementaors of a new type of polynomial ring should see `src/generic/GenericTypes.jl`
+for an example of how to implement such a cache (which usually makes use of a dictionary).
+In particular look at `MPolyID`.
 
 ## Required functionality for multivariate polynomials
 

docs/src/poly_interface.md

@@ -135,15 +135,19 @@ Return the array `[s]` where `s` is a `Symbol` representing the variable of the
 polynomial ring. This is provided for uniformity with the multivariate interface, where
 there is more than one variable and hence an array of symbols.
 
-```julia
-poly_type(::Type{T}) where T <: RingElement
+Given a type for the coefficients, we can obtain the corresponding type of a
+univariate polynomial having that type of coefficient:
+
+```@docs
+poly_type
 ```
 
-Return the type of a polynomial whose coefficients have the given type. In our
-example `MyPoly{T}`.
+Analogously, given a type for the coefficients, we can obtain the corresponding
+type of the ring of univariate polynomials having that type of coefficient:
 
-This function is defined for generic polynomials and only needs to be defined for
-custom polynomial rings, e.g. ones defined by a C implementation.
+```@docs
+poly_ring_type
+```
 
 ```@docs
 poly_ring(R::Ring, s::Symbol; cached::Bool=false)

src/MPoly.jl

@@ -21,10 +21,17 @@ coefficient_ring(R::MPolyRing) = base_ring(R)
     mpoly_type(::Type{S}) where S<:Ring
     mpoly_type(::S) where S<:Ring
 
-The type of multivariate polynomials with coefficients of type `T` respectively `elem_type(S)`.
-Falls back to `Generic.MPoly{T}`.
+Return the type of a (multivariate) polynomial whose coefficients have type `T` or
+type `elem_type(S)`.
+The type of the corresponding polynomial ring can be found via [`mpoly_ring_type`](@ref).
 
-See also [`mpoly_ring_type`](@ref), [`poly_type`](@ref) and [`poly_ring_type`](@ref).
+For univariate polynomials see [`poly_type`](@ref).
+
+# Implementation
+
+This function is already defined for generic multivariate polynomials (namely `Generic.MPoly{T}`),
+so _needs to be defined only for_ special polynomial rings, _e.g._ those defined by
+a C implementation.
 
 # Examples
 ```jldoctest
@@ -41,6 +48,8 @@ julia> mpoly_type(typeof(AbstractAlgebra.ZZ))
 AbstractAlgebra.Generic.MPoly{BigInt}
 ```
 """
+mpoly_type
+
 mpoly_type(::Type{T}) where T<:RingElement = Generic.MPoly{T}
 mpoly_type(::Type{S}) where S<:Ring = mpoly_type(elem_type(S))
 mpoly_type(x) = mpoly_type(typeof(x)) # to stop this method from eternally recursing on itself, we better add ...
@@ -53,10 +62,18 @@ mpoly_type(T::Type{Union{}}) = throw(MethodError(mpoly_type, (T,)))
     mpoly_ring_type(::Type{S}) where S<:Ring
     mpoly_ring_type(::S) where S<:Ring
 
-The type of multivariate polynomial rings with coefficients of type `T`
-respectively `elem_type(S)`. Implemented via [`mpoly_type`](@ref).
+Return the type of the parent of a (multivariate) polynomial whose coefficients
+have type `T` or type `elem_type(S)`.
+The type of the polynomials themselves can be found via [`mpoly_type`](@ref).
+
+For univariate polynomials see [`poly_ring_type`](@ref).
+
+# Implementation 
+
+This function is already defined for generic multivariate polynomials (namely `Generic.MPoly{T}`),
+so _needs to be defined only for_ special polynomial rings, _e.g._ those defined by
+a C implementation.
 
-See also [`poly_type`](@ref) and [`poly_ring_type`](@ref).
 
 # Examples
 ```jldoctest

src/NCPoly.jl

@@ -25,10 +25,17 @@ end
     poly_type(::Type{S}) where S<:NCRing
     poly_type(::S) where S<:NCRing
 
-The type of univariate polynomials with coefficients of type `T` respectively `elem_type(S)`.
-Falls back to `Generic.NCPoly{T}` respectively `Generic.Poly{T}`.
+Return the type of a (univariate) polynomial whose coefficients have type `T` or
+type `elem_type(S)`.
+The type of the corresponding polynomial ring can be found via [`poly_ring_type`](@ref).
 
-See also [`poly_ring_type`](@ref), [`mpoly_type`](@ref) and [`mpoly_ring_type`](@ref).
+For multivariate polynomials see [`mpoly_ring_type`](@ref).
+
+# Implementation 
+
+This function is already defined for generic univariate polynomials (namely `Generic.NCPoly{T}` or `Generic.Poly{T}`),
+so _needs to be defined only for_ special polynomial rings, _e.g._ those defined by
+a C implementation.
 
 # Examples
 ```jldoctest
@@ -45,6 +52,8 @@ julia> poly_type(typeof(AbstractAlgebra.ZZ))
 AbstractAlgebra.Generic.Poly{BigInt}
 ```
 """
+poly_type
+
 poly_type(::Type{T}) where T<:NCRingElement = Generic.NCPoly{T}
 poly_type(::Type{S}) where S<:NCRing = poly_type(elem_type(S))
 poly_type(x) = poly_type(typeof(x)) # to stop this method from eternally recursing on itself, we better add ...