condense doc for sqrt into single docstring (#2226)

Author: varuntrehan7

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