Condense doc for is_square into single docstring

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,17 @@ function is_nilpotent(a::T) where {T <: NCRingElement}
 end
 
 
+@doc raw"""
+    is_square(a::T)  where {T <: NCRingElement}
+    is_square(M::MatElem)
+    is_square(M::MatRingElem)
+
+There are two distinct situations:
+(1) if the argument is matrix then check whether the matrix **shape** is square
+(2) if the argument is not a matrix then check whether the **value** is a square (in the same ring)
+"""
+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,7 @@ end
 #
 ################################################################################
 
+# 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