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/Fraction.jl

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

src/MatRing.jl

@@ -152,7 +152,7 @@ end
 #
 ################################################################################
 
-is_square(a::MatRingElem) = true
+# 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,6 @@ 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.
-"""
 function is_square(f::PolyRingElem{T}) where T <: RingElement
    flag, q = sqrt_classical(f)
    return flag

src/ResidueField.jl

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

src/generic/Matrix.jl

@@ -101,6 +101,12 @@ end
 #
 ################################################################################
 
+@doc raw"""
+    is_square(M::MatElem)
+
+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.
+"""
 is_square(a::MatElem) = (nrows(a) == ncols(a))
 
 ###############################################################################

src/generic/RationalFunctionField.jl

@@ -451,11 +451,6 @@ end
 #
 ###############################################################################
 
-@doc raw"""
-    is_square(a::RationalFunctionFieldElem)
-
-Return `true` if $a$ is a square.
-"""
 function is_square(a::RationalFunctionFieldElem)
    return is_square(data(a))
 end

src/julia/Float.jl

@@ -144,11 +144,11 @@ function Base.sqrt(a::AbstractFloat; check::Bool=true)
 end
 
 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/Integer.jl

@@ -311,11 +311,6 @@ 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.
-"""
 function is_square(a::T) where T <: Integer
    if a < 0
       return false

test/generic/MatRing-test.jl

@@ -208,7 +208,6 @@ end
 
    A = S([t + 1 t R(1); t^2 t t; R(-2) t + 2 t^2 + t + 1])
 
-   @test is_square(A)
    @test size(A) == (3, 3)
    @test size(A, 1) == 3
    @test size(A, 2) == 3
@@ -234,7 +233,6 @@ end
    @test size(M, 1) == 2
    @test axes(M) == (1:2, 1:2)
    @test axes(M, 1) == 1:2
-   @test is_square(M)
 end
 
 @testset "Generic.MatAlg.unary_ops" begin

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)