Condense doc for is_square into single docstring

docs/src/fraction.md

@@ -301,10 +301,6 @@ julia> h = gcd(f, g)
 
 ### Square root
 
-```@docs
-is_square{T <: RingElem}(::FracElem{T})
-```
-
 ```@docs
 Base.sqrt(::FracElem{T}) where {T <: RingElem}
 ```

docs/src/function_field.md

@@ -162,10 +162,6 @@ julia> h = gcd(f, g)
 
 ### Square root
 
-```@docs
-is_square(::Generic.RationalFunctionFieldElem{T, U}) where {T <: FieldElem, U <: Union{PolyRingElem, MPolyRingElem}}
-```
-
 ```@docs
 Base.sqrt(::Generic.RationalFunctionFieldElem{T, U}) where {T <: FieldElem, U <: Union{PolyRingElem, MPolyRingElem}}
 ```

docs/src/integer.md

@@ -166,7 +166,6 @@ AbstractAlgebra.sqrt(a::BigInt)
 ```
 
 ```@docs
-is_square(a::BigInt)
 is_square_with_sqrt(a::BigInt)
 ```
 

docs/src/polynomial.md

@@ -405,10 +405,6 @@ is_gen(::PolyRingElem)
 is_monic(::PolyRingElem)
 ```
 
-```@docs
-is_square(::PolyRingElem)
-```
-
 ```@docs
 length(::PolynomialElem)
 ```

docs/src/residue.md

@@ -264,10 +264,6 @@ julia> h = gcd(f, g)
 
 ### Square Root
 
-```@docs
-is_square{T <: Integer}(::ResFieldElem{T})
-```
-
 ```@docs
 Base.sqrt{T <: Integer}(::ResFieldElem{T})
 ```

src/AbsSeries.jl

@@ -920,6 +920,7 @@ function Base.sqrt(a::AbsPowerSeriesRingElem; check::Bool=true)
    return q
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::AbsPowerSeriesRingElem)
    flag, q = sqrt_classical(a; check=true)
    return flag

src/Fraction.jl

@@ -693,11 +693,7 @@ end
 #
 ###############################################################################
 
-@doc raw"""
-    is_square(a::FracElem{T}) where T <: RingElem
-
-Return `true` if $a$ is a square.
-"""
+# See generic documentation in NCRings.jl
 function is_square(a::FracElem{T}) where T <: RingElem
    return is_square(numerator(a)) && is_square(denominator(a))
 end

src/MatRing.jl

@@ -152,6 +152,7 @@ end
 #
 ################################################################################
 
+# See generic documentation in NCRings.jl
 is_square(a::MatRingElem) = true
 
 ###############################################################################

src/NCRings.jl

@@ -176,6 +176,14 @@ function is_nilpotent(a::T) where {T <: NCRingElement}
 end
 
 
+@doc raw"""
+    is_square(a::T)  where {T <: NCRingElement}
+
+Return `true` iff `a` is the square of a value in its own ring.
+See also `is_square(M::MatElem)` which tests whether a matrix has square shape.
+"""
+function is_square end
+
 ###############################################################################
 #
 #   Characteristic

src/Poly.jl

@@ -1837,11 +1837,7 @@ function Base.sqrt(f::PolyRingElem{T}; check::Bool=true) where T <: RingElement
    return q
 end
 
-@doc raw"""
-    is_square(f::PolyRingElem{T}) where T <: RingElement
-
-Return `true` if $f$ is a perfect square.
-"""
+# See generic documentation in NCRings.jl
 function is_square(f::PolyRingElem{T}) where T <: RingElement
    flag, q = sqrt_classical(f)
    return flag

src/RelSeries.jl

@@ -1187,6 +1187,7 @@ function Base.sqrt(a::RelPowerSeriesRingElem; check::Bool=true)
    return q
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::RelPowerSeriesRingElem)
    flag, q = sqrt_classical(a; check=true)
    return flag

src/ResidueField.jl

@@ -340,11 +340,7 @@ end
 #
 ###############################################################################
 
-@doc raw"""
-    is_square(a::ResFieldElem{T}) where T <: Integer
-
-Return `true` if $a$ is a square.
-"""
+# See generic documentation in NCRings.jl
 function is_square(a::ResFieldElem{T}) where T <: Integer
    if iszero(a)
       return true

src/generic/LaurentSeries.jl

@@ -1408,6 +1408,7 @@ function Base.sqrt(a::LaurentSeriesElem; check::Bool=true)
    return s
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::LaurentSeriesElem)
    flag, q = sqrt_classical(a; check=true)
    return flag

src/generic/MPoly.jl

@@ -1872,6 +1872,7 @@ function Base.sqrt(a::MPoly{T}; check::Bool=true) where {T <: RingElement}
    return q
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::MPoly{T}) where {T <: RingElement}
    flag, q = sqrt_heap(a; check=true)
    return flag

src/generic/Matrix.jl

@@ -101,6 +101,14 @@ end
 #
 ################################################################################
 
+@doc raw"""
+    is_square(M::MatElem)
+    is_square(M::MatRingElem)
+
+Return `true` iff the matrix `M` has square shape.
+See also `is_square(a::T)  where {T <: NCRingElement}` which tests whether the given value `a` is a square in its own ring.
+"""
+# See generic documentation in NCRings.jl
 is_square(a::MatElem) = (nrows(a) == ncols(a))
 
 ###############################################################################

src/generic/PuiseuxSeries.jl

@@ -626,6 +626,7 @@ function Base.sqrt(a::PuiseuxSeriesElem{T}; check::Bool=true) where T <: RingEle
    return s
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::PuiseuxSeriesElem{T}) where T <: RingElement
    flag, s = sqrt_classical(a; check=true)
    return flag

src/generic/RationalFunctionField.jl

@@ -451,11 +451,7 @@ end
 #
 ###############################################################################
 
-@doc raw"""
-    is_square(a::RationalFunctionFieldElem)
-
-Return `true` if $a$ is a square.
-"""
+# See generic documentation in NCRings.jl
 function is_square(a::RationalFunctionFieldElem)
    return is_square(data(a))
 end

src/generic/UnivPoly.jl

@@ -534,6 +534,7 @@ function Base.sqrt(p::UnivPoly{T}; check::Bool=true) where {T}
    return UnivPoly{T}(s, S)
 end
 
+# See generic documentation in NCRings.jl
 function is_square(p::UnivPoly)
    return is_square(data(p))
 end

src/julia/Float.jl

@@ -143,12 +143,13 @@ function Base.sqrt(a::AbstractFloat; check::Bool=true)
    return Base.sqrt(a)
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::AbstractFloat)
-   return a > 0
+   return a >= 0
 end
 
 function is_square_with_sqrt(a::T) where T <: AbstractFloat
-   if a > 0
+   if a >= 0
       return true, Base.sqrt(a)
    else
       return false, zero(T)

src/julia/GF.jl

@@ -332,6 +332,7 @@ function Base.sqrt(a::GFElem{T}; check::Bool=true) where T <: Integer
    return s1
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::GFElem{T}) where T <: Integer
    f1, s1 = sqrt_tonelli_shanks(a; check=true)
    return f1

src/julia/Integer.jl

@@ -311,11 +311,7 @@ function is_square_with_sqrt(a::BigInt)
    end
 end
 
-@doc raw"""
-    is_square(a::T) where T <: Integer
-
-Return true if $a$ is a square.
-"""
+# See generic documentation in NCRings.jl
 function is_square(a::T) where T <: Integer
    if a < 0
       return false
@@ -324,6 +320,7 @@ function is_square(a::T) where T <: Integer
    return a == s*s
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::BigInt)
    if a < 0
       return false

src/julia/Rational.jl

@@ -132,6 +132,7 @@ function sqrt(a::Rational{T}; check::Bool=true) where T <: Integer
    return sqrt(numerator(a, false); check=check)//sqrt(denominator(a, false); check=check)
 end
 
+# See generic documentation in NCRings.jl
 function is_square(a::Rational{T}) where T <: Integer
    return is_square(numerator(a)) && is_square(denominator(a))
 end

test/julia/Floats-test.jl

@@ -83,13 +83,26 @@ end
    end
 end
 
-@testset "Julia.Floats.gcd" begin
+@testset "Julia.Floats.is_square" begin
    R = RDF
    S = RealField
 
+   z1 = R(0.0)
+   z2 = S(0.0)
+
+   @test is_square(z1)
+   @test is_square(z2)
+
+   fz1, z1root = is_square_with_sqrt(z1)
+   @test fz1
+   @test is_zero(z1root)
+
+   fz2, z2root = is_square_with_sqrt(z2)
+   @test fz2
+   @test is_zero(z2root)
+
    r = R(-0.1)
    s = S(-0.1)
-
    @test !is_square(r)
    @test !is_square(s)