condense doc for sqrt into single docstring

docs/src/fraction.md

@@ -301,9 +301,7 @@ julia> h = gcd(f, g)
 
 ### Square root
 
-```@docs
-Base.sqrt(::FracElem{T}) where {T <: RingElem}
-```
+Methods for `is_square` and `sqrt` are provided for inputs of type `FracElem`.
 
 **Examples**
 

docs/src/function_field.md

@@ -162,9 +162,7 @@ julia> h = gcd(f, g)
 
 ### Square root
 
-```@docs
-Base.sqrt(::Generic.RationalFunctionFieldElem{T, U}) where {T <: FieldElem, U <: Union{PolyRingElem, MPolyRingElem}}
-```
+Methods for `is_square` and `sqrt` are provided for inputs of type `RationalFunctionFieldElem`.
 
 **Examples**
 

docs/src/polynomial.md

@@ -674,9 +674,7 @@ deflate(::PolyRingElem)
 
 ### Square root
 
-```@docs
-Base.sqrt(::PolyRingElem{T}; check::Bool) where T <: RingElement
-```
+Methods for `is_square` and `sqrt` are provided for inputs of type `PolyRingElem`.
 
 **Examples**
 

docs/src/puiseux.md

@@ -328,11 +328,7 @@ true
 Base.log(a::Generic.PuiseuxSeriesElem)
 Base.exp(a::Generic.PuiseuxSeriesElem)
 ```
-
-```@docs
-Base.sqrt(a::Generic.PuiseuxSeriesElem)
-```
-
+Methods for `is_square` and `sqrt` are provided for inputs of type `PuiseuxSeriesElem`.
 
 **Examples**
 

docs/src/residue.md

@@ -264,9 +264,7 @@ julia> h = gcd(f, g)
 
 ### Square Root
 
-```@docs
-Base.sqrt{T <: Integer}(::ResFieldElem{T})
-```
+Methods for `is_square` and `sqrt` are provided for inputs of type `ResFieldElem`.
 
 **Examples**
 

docs/src/ring.md

@@ -252,6 +252,17 @@ evaluate(a::Fac)
 getindex(a::Fac, b)
 setindex!(a::Fac{Int}, c::Int, b::Int)
 ```
+## Square root
+
+Rings may implement functionality for detecting and computing square roots.
+
+The exact behaviour depends on the ring. Some rings provide both operations,
+while others only implement `is_square`.
+
+```@docs
+is_square
+sqrt(::NCRingElem)
+```
 
 ## Miscellaneous
 

docs/src/series.md

@@ -686,10 +686,7 @@ Base.log(a::SeriesElem{T}) where T <: FieldElem
 ```@docs
 Base.exp(a::RelPowerSeriesRingElem)
 ```
-
-```@docs
-Base.sqrt(a::RelPowerSeriesRingElem)
-```
+Methods for `is_square` and `sqrt` are provided for inputs of type `RelPowerSeriesRingElem`.
 
 
 **Examples**

src/AbsSeries.jl

@@ -905,13 +905,6 @@ function sqrt_classical(a::AbsPowerSeriesRingElem; check::Bool=true)
    return true, asqrt
 end
 
-@doc raw"""
-    sqrt(a::AbsPowerSeriesRingElem; check::Bool=true)
-
-Return the square root of the power series $a$. By default the function will
-throw an exception if the input is not square. If `check=false` this test is
-omitted.
-"""
 function Base.sqrt(a::AbsPowerSeriesRingElem; check::Bool=true)
    flag, q = sqrt_classical(a; check=check)
    if check && !flag

src/Fraction.jl

@@ -697,12 +697,6 @@ function is_square(a::FracElem{T}) where T <: RingElem
    return is_square(numerator(a)) && is_square(denominator(a))
 end
 
-@doc raw"""
-    Base.sqrt(a::FracElem{T}; check::Bool=true) where T <: RingElem
-
-Return the square root of $a$. By default the function will throw an
-exception if the input is not square. If `check=false` this test is omitted.
-"""
 function Base.sqrt(a::FracElem{T}; check::Bool=true) where T <: RingElem
    return parent(a)(sqrt(numerator(a); check=check), sqrt(denominator(a); check=check))
 end

src/NCRings.jl

@@ -184,6 +184,17 @@ See also `is_square(M::MatElem)` which tests whether a matrix has square shape.
 """
 function is_square end
 
+@doc raw"""
+    sqrt(a::NCRingElem; check::Bool=true)
+
+Return a square root of `a`, if it exists. By default (`check=true`),
+implementations should raise an exception if `a` is not a square in its ring.
+If `check=false`, implementations may skip this verification.
+
+See also `is_square` and `is_square_with_sqrt`.
+"""
+sqrt(::NCRingElem)
+
 ###############################################################################
 #
 #   Characteristic

src/Poly.jl

@@ -1825,12 +1825,6 @@ function sqrt_classical(f::PolyRingElem{T}; check::Bool=true) where T <: RingEle
    return true, q
 end
 
-@doc raw"""
-    Base.sqrt(f::PolyRingElem{T}; check::Bool=true) where T <: RingElement
-
-Return the square root of $f$. By default the function checks the input is
-square and raises an exception if not. If `check=false` this check is omitted.
-"""
 function Base.sqrt(f::PolyRingElem{T}; check::Bool=true) where T <: RingElement
    flag, q = sqrt_classical(f; check=check)
    check && !flag && error("Not a square in sqrt")

src/RelSeries.jl

@@ -1172,13 +1172,6 @@ function sqrt_classical(a::RelPowerSeriesRingElem; check::Bool=true)
    return true, asqrt
 end
 
-@doc raw"""
-    sqrt(a::RelPowerSeriesRingElem)
-
-Return the square root of the power series $a$. By default the function raises
-an exception if the input is not a square. If `check=false` this check is
-omitted.
-"""
 function Base.sqrt(a::RelPowerSeriesRingElem; check::Bool=true)
    flag, q = sqrt_classical(a; check=check)
    if check && !flag

src/ResidueField.jl

@@ -349,12 +349,6 @@ function is_square(a::ResFieldElem{T}) where T <: Integer
    return isone(a^pm1div2)
 end
 
-@doc raw"""
-    sqrt(a::ResFieldElem{T}; check::Bool=true) where T <: Integer
-
-Return the square root of $a$. By default the function will throw an exception
-if the input is not square. If `check=false` this test is omitted.
-"""
 function Base.sqrt(a::ResFieldElem{T}; check::Bool=true) where T <: Integer
    U = parent(a)
    p = modulus(a)

src/Rings.jl

@@ -160,13 +160,6 @@ end
 #
 ################################################################################
 
-@doc raw"""
-    sqrt(a::FieldElem)
-
-Return the square root of the element `a`. By default the function will
-throw an exception if the input is not square. If `check=false` this test is
-omitted.
-"""
 function Base.sqrt(a::FieldElem; check::Bool=true)
   R = parent(a)
   R, t = polynomial_ring(R, :t; cached = false)

src/generic/LaurentSeries.jl

@@ -1395,13 +1395,6 @@ function sqrt_classical(a::LaurentSeriesElem; check::Bool=true)
     return true, asqrt
 end
 
-@doc raw"""
-    sqrt(a::Generic.LaurentSeriesElem; check::Bool=true)
-
-Return the square root of the power series $a$. By default the function will
-throw an exception if the input is not square. If `check=false` this test is
-omitted.
-"""
 function Base.sqrt(a::LaurentSeriesElem; check::Bool=true)
    flag, s = sqrt_classical(a, check=check)
    check && !flag && error("Not a square in sqrt")

src/generic/PuiseuxSeries.jl

@@ -613,13 +613,6 @@ function sqrt_classical(a::PuiseuxSeriesElem{T}; check::Bool=true) where T <: Ri
    return true, S(s, sscale)
 end
 
-@doc raw"""
-    sqrt(a::Generic.PuiseuxSeriesElem{T}; check::Bool=true) where T <: RingElement
-
-Return the square root of the given Puiseux series $a$. By default the function
-will throw an exception if the input is not square. If `check=false` this test
-is omitted.
-"""
 function Base.sqrt(a::PuiseuxSeriesElem{T}; check::Bool=true) where T <: RingElement
    flag, s = sqrt_classical(a; check=check)
    check && !flag && error("Not a square in sqrt")

src/generic/RationalFunctionField.jl

@@ -455,12 +455,6 @@ function is_square(a::RationalFunctionFieldElem)
    return is_square(data(a))
 end
 
-@doc raw"""
-    Base.sqrt(a::RationalFunctionFieldElem; check::Bool=true)
-
-Return the square root of $a$. By default the function will throw an exception
-if the input is not square. If `check=false` this test is omitted.
-"""
 function Base.sqrt(a::RationalFunctionFieldElem; check::Bool=true)
    R = parent(a)
    return R(sqrt(data(a); check=check))