From f19a27da1bf215ac253191cc2bada29d87693850 Mon Sep 17 00:00:00 2001
From: Max Horn <max@quendi.de>
Date: Tue, 12 Nov 2024 09:09:30 +0100
Subject: [PATCH] Untangle docstrings for similar, zero; MatElem, MatRingElem

---
 src/MatRing.jl | 30 ++++++++----------------------
 src/Matrix.jl  | 40 ++++++++++++++++++++++++----------------
 2 files changed, 32 insertions(+), 38 deletions(-)

diff --git a/src/MatRing.jl b/src/MatRing.jl
index e2d2b96001..6568f27172 100644
--- a/src/MatRing.jl
+++ b/src/MatRing.jl
@@ -79,46 +79,32 @@ is_finite(R::MatRing) = iszero(nrows(a)) || is_finite(base_ring(R))
 ###############################################################################
 
 @doc raw"""
-    similar(x::Generic.MatrixElem, R::NCRing, r::Int, c::Int)
-    similar(x::Generic.MatrixElem, R::NCRing)
-    similar(x::Generic.MatrixElem, r::Int, c::Int)
-    similar(x::Generic.MatrixElem)
     similar(x::MatRingElem, R::NCRing, n::Int)
     similar(x::MatRingElem, R::NCRing)
     similar(x::MatRingElem, n::Int)
     similar(x::MatRingElem)
 
-Create an uninitialized matrix over the given ring and dimensions,
-with defaults based upon the given source matrix `x`.
+Create an uninitialized matrix ring element over the given ring and dimension,
+with defaults based upon the given source matrix ring element `x`.
 """
-function similar(x::MatRingElem, R::NCRing, n::Int)
+function similar(x::MatRingElem, R::NCRing=base_ring(x), n::Int=degree(x))
    TT = elem_type(R)
    M = Matrix{TT}(undef, (n, n))
    return Generic.MatRingElem{TT}(R, M)
 end
 
-similar(x::MatRingElem, R::NCRing=base_ring(x)) = similar(x, R, degree(x))
-
 similar(x::MatRingElem, n::Int) = similar(x, base_ring(x), n)
 
-function similar(x::MatRingElem{T}, R::NCRing, m::Int, n::Int) where T <: NCRingElement
-   m != n && error("Dimensions don't match in similar")
-   return similar(x, R, n)
-end
-
-similar(x::MatRingElem, m::Int, n::Int) = similar(x, base_ring(x), m, n)
-
 @doc raw"""
-    zero(x::MatrixElem, R::NCRing=base_ring(x))
-    zero(x::MatrixElem, R::NCRing, r::Int, c::Int)
-    zero(x::MatrixElem, r::Int, c::Int)
     zero(x::MatRingElem, R::NCRing, n::Int)
+    zero(x::MatRingElem, R::NCRing)
     zero(x::MatRingElem, n::Int)
+    zero(x::MatRingElem)
 
-Create a zero matrix over the given ring and dimensions,
-with defaults based upon the given source matrix `x`.
+Create a zero matrix ring element over the given ring and dimension,
+with defaults based upon the given source matrix ring element `x`.
 """
-zero(x::MatRingElem, R::NCRing, n::Int) = zero!(similar(x, R, n))
+zero(x::MatRingElem, R::NCRing=base_ring(x), n::Int=degree(x)) = zero!(similar(x, R, n))
 zero(x::MatRingElem, n::Int) = zero!(similar(x, n))
 
 ################################################################################
diff --git a/src/Matrix.jl b/src/Matrix.jl
index 1b29c5fe6c..74b92586cf 100644
--- a/src/Matrix.jl
+++ b/src/Matrix.jl
@@ -229,20 +229,6 @@ Return the zero matrix in the given matrix space.
 """
 zero(a::MatSpace) = a()
 
-@doc raw"""
-    zero(x::MatrixElem{T}, R::NCRing, r::Int, c::Int) where T <: NCRingElement
-    zero(x::MatrixElem{T}, r::Int, c::Int) where T <: NCRingElement
-    zero(x::MatrixElem{T}, R::NCRing) where T <: NCRingElement
-    zero(x::MatrixElem{T}) where T <: NCRingElement
-
-Return a zero matrix similar to the given matrix, with optionally different
-base ring or dimensions.
-"""
-zero(x::MatrixElem{T}, R::NCRing) where T <: NCRingElement = zero(x, R, nrows(x), ncols(x))
-zero(x::MatrixElem{T}) where T <: NCRingElement = zero(x, nrows(x), ncols(x))
-zero(x::MatrixElem{T}, R::NCRing, r::Int, c::Int) where T <: NCRingElement = zero!(similar(x, R, r, c))
-zero(x::MatrixElem{T}, r::Int, c::Int) where T <: NCRingElement = zero!(similar(x, r, c))
-
 @doc raw"""
     one(a::MatSpace)
 
@@ -400,14 +386,36 @@ end
 #
 ###############################################################################
 
-similar(x::MatElem, R::NCRing, r::Int, c::Int) = zero_matrix(R, r, c)
+@doc raw"""
+    similar(x::MatElem{T}, R::NCRing, r::Int, c::Int) where T <: NCRingElement
+    similar(x::MatElem{T}, R::NCRing) where T <: NCRingElement
+    similar(x::MatElem{T}, r::Int, c::Int) where T <: NCRingElement
+    similar(x::MatElem{T}) where T <: NCRingElement
 
+Create an uninitialized matrix over the given ring and dimensions,
+with defaults based upon the given source matrix `x`."""
+similar(x::MatElem, R::NCRing, r::Int, c::Int) = zero_matrix(R, r, c)
+  
 similar(x::MatElem, R::NCRing) = similar(x, R, nrows(x), ncols(x))
 
 similar(x::MatElem, r::Int, c::Int) = similar(x, base_ring(x), r, c)
 
 similar(x::MatElem) = similar(x, nrows(x), ncols(x))
 
+@doc raw"""
+    zero(x::MatElem{T}, R::NCRing, r::Int, c::Int) where T <: NCRingElement
+    zero(x::MatElem{T}, r::Int, c::Int) where T <: NCRingElement
+    zero(x::MatElem{T}, R::NCRing) where T <: NCRingElement
+    zero(x::MatElem{T}) where T <: NCRingElement
+
+Create an zero matrix over the given ring and dimensions,
+with defaults based upon the given source matrix `x`."""
+"""
+zero(x::MatElem{T}, R::NCRing) where T <: NCRingElement = zero(x, R, nrows(x), ncols(x))
+zero(x::MatElem{T}) where T <: NCRingElement = zero(x, nrows(x), ncols(x))
+zero(x::MatElem{T}, R::NCRing, r::Int, c::Int) where T <: NCRingElement = zero!(similar(x, R, r, c))
+zero(x::MatElem{T}, r::Int, c::Int) where T <: NCRingElement = zero!(similar(x, r, c))
+
 ###############################################################################
 #
 #   Canonicalisation
@@ -1011,7 +1019,7 @@ function +(x::T, y::MatrixElem{T}) where {T <: NCRingElem}
 end
 
 @doc raw"""
-    +(x::Generic.MatrixElem{T}, y::T) where {T <: RingElem}
+    +(x::MatrixElem{T}, y::T) where {T <: RingElem}
 
 Return $x + S(y)$ where $S$ is the parent of $x$.
 """