From 91abbed797fc94475402e8cdb217ef2924101ef0 Mon Sep 17 00:00:00 2001
From: leburgel <lander.burgelman@gmail.com>
Date: Mon, 6 Oct 2025 12:22:58 +0200
Subject: [PATCH 1/2] Some doc fixes and additions for spin operators

---
 src/operators/spinoperators.jl | 71 ++++++++++++++++++++++++----------
 1 file changed, 50 insertions(+), 21 deletions(-)

diff --git a/src/operators/spinoperators.jl b/src/operators/spinoperators.jl
index b4238cb..47f06f8 100644
--- a/src/operators/spinoperators.jl
+++ b/src/operators/spinoperators.jl
@@ -50,7 +50,7 @@ end
 
 The spin operator along the x-axis.
 
-See also [`σˣ`](@ref)
+See also [`σˣ`](@ref).
 """
 function S_x end
 S_x(; kwargs...) = S_x(ComplexF64, Trivial; kwargs...)
@@ -99,7 +99,11 @@ end
 
 const Sˣ = S_x
 
-"""Pauli x operator."""
+"""
+Pauli ``x`` operator, defined as ``σˣ = 2 ⋅ Sˣ``.
+
+See also [`Sˣ`](@ref).
+"""
 σˣ(args...; kwargs...) = 2 * S_x(args...; kwargs...)
 
 """
@@ -108,7 +112,7 @@ const Sˣ = S_x
 
 The spin operator along the y-axis.
 
-See also [`σʸ`](@ref)
+See also [`σʸ`](@ref).
 """
 function S_y end
 S_y(; kwargs...) = S_y(ComplexF64, Trivial; kwargs...)
@@ -170,7 +174,11 @@ end
 
 const Sʸ = S_y
 
-"""Pauli y operator."""
+"""
+Pauli ``y`` operator, defined as ``σʸ = 2 ⋅ Sʸ``.
+
+See also [`Sʸ`](@ref).
+"""
 σʸ(args...; kwargs...) = 2 * S_y(args...; kwargs...)
 
 """
@@ -180,7 +188,7 @@ const Sʸ = S_y
 The spin operator along the z-axis. Possible values for `symmetry` are `Trivial`, `Z2Irrep`,
 and `U1Irrep`.
 
-See also [`σᶻ`](@ref)
+See also [`σᶻ`](@ref).
 """
 function S_z end
 S_z(; kwargs...) = S_z(ComplexF64, Trivial; kwargs...)
@@ -223,7 +231,11 @@ end
 
 const Sᶻ = S_z
 
-"""Pauli z operator."""
+"""
+Pauli ``z`` operator, defined as ``σᶻ = 2 ⋅ Sᶻ``.
+
+See also [`Sᶻ`](@ref).
+"""
 σᶻ(args...; kwargs...) = 2 * S_z(args...; kwargs...)
 
 """
@@ -232,7 +244,7 @@ const Sᶻ = S_z
 
 The spin plus operator.
 
-See also [`σ⁺`](@ref)
+See also [`σ⁺`](@ref).
 """
 function S_plus end
 S_plus(; kwargs...) = S_plus(ComplexF64, Trivial; kwargs...)
@@ -284,7 +296,11 @@ end
 
 const S⁺ = S_plus
 
-"""Pauli plus operator."""
+"""
+Pauli plus operator, defined as ``σ⁺ = 2 ⋅ S⁺``.
+
+See also [`S⁺`](@ref).
+"""
 σ⁺(args...; kwargs...) = 2 * S_plus(args...; kwargs...)
 
 """
@@ -293,7 +309,7 @@ const S⁺ = S_plus
 
 The spin minus operator.
 
-See also [`σ⁻`](@ref)
+See also [`σ⁻`](@ref).
 """
 function S_min end
 S_min(; kwargs...) = S_min(ComplexF64, Trivial; kwargs...)
@@ -345,7 +361,11 @@ end
 
 const S⁻ = S_min
 
-"""Pauli minus operator."""
+"""
+Pauli minus operator, defined as ``σ⁻ = 2 ⋅ S⁻``.
+
+See also [`S⁻`](@ref).
+"""
 σ⁻(args...; kwargs...) = 2 * S_min(args...; kwargs...)
 
 unicode_table = Dict(:x => :ˣ, :y => :ʸ, :z => :ᶻ, :plus => :⁺, :min => :⁻)
@@ -355,13 +375,18 @@ function spinop_docstring(L::Symbol, R::Symbol)
     S_$L$R([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
     $(Symbol(:S, unicode_table[L], unicode_table[R]))([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
 
-The spin $L$R exchange operator.
+    The spin $L$R exchange operator.
 
-See also [`σ$(unicode_table[L])$(unicode_table[R])`](@ref)
-"""
+    See also [`σ$(unicode_table[L])$(unicode_table[R])`](@ref).
+    """
 end
 function pauli_unicode_docstring(L::Symbol, R::Symbol)
-    return """Pauli $L$R operator."""
+    doc = """
+    Pauli $L$R operator, defined as ``σ$(unicode_table[L])$(unicode_table[R]) = 4 ⋅ S$(unicode_table[L])$(unicode_table[R])``.
+
+    See also [`S$(unicode_table[L])$(unicode_table[R])`](@ref).
+    """
+    return doc
 end
 
 for (L, R) in ((:x, :x), (:y, :y), (:z, :z), (:plus, :min), (:min, :plus))
@@ -409,7 +434,7 @@ end
 
 The spin exchange operator.
 
-See also [`σσ`](@ref)
+See also [`σσ`](@ref).
 """
 function S_exchange end
 S_exchange(; kwargs...) = S_exchange(ComplexF64, Trivial; kwargs...)
@@ -437,7 +462,11 @@ end
 
 const SS = S_exchange
 
-"""Pauli exchange operator."""
+"""
+Pauli exchange operator, defined as ``σσ = 4 ⋅ SS``.
+
+See also [`SS`](@ref).
+"""
 σσ(args...; kwargs...) = 4 * S_exchange(args...; kwargs...)
 
 """
@@ -491,9 +520,9 @@ function weyl_heisenberg_matrices(Q::Int, elt=ComplexF64)
 end
 
 """
-    potts_Z([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; Q=3)
+    potts_Z([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; q=3)
 
-The Potts Z operator, also known as the clock operator, where Z^q=1.
+The Potts ``Z`` operator, also known as the clock operator, where ``Z^q = 1``.
 """
 function potts_Z end
 potts_Z(; kwargs...) = potts_Z(ComplexF64, Trivial; kwargs...)
@@ -506,10 +535,10 @@ function potts_Z(elt::Type{<:Number}, ::Type{Trivial}; q=3)
 end
 
 """
-    potts_X([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; Q=3)
-    potts_field([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; Q=3)
+    potts_X([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; q=3)
+    potts_field([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; q=3)
 
-The Potts X operator, also known as the shift operator, where X^q=1.
+The Potts ``X`` operator, also known as the shift operator, where ``X^q = 1``.
 """
 function potts_X end
 potts_X(; kwargs...) = potts_X(ComplexF64, Trivial; kwargs...)

From d4030383cb14363419c01159d138730b2628491d Mon Sep 17 00:00:00 2001
From: leburgel <lander.burgelman@gmail.com>
Date: Mon, 6 Oct 2025 12:42:53 +0200
Subject: [PATCH 2/2] Fix some mistakes

---
 src/operators/spinoperators.jl | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/operators/spinoperators.jl b/src/operators/spinoperators.jl
index 47f06f8..07858ef 100644
--- a/src/operators/spinoperators.jl
+++ b/src/operators/spinoperators.jl
@@ -102,7 +102,7 @@ const Sˣ = S_x
 """
 Pauli ``x`` operator, defined as ``σˣ = 2 ⋅ Sˣ``.
 
-See also [`Sˣ`](@ref).
+See also [`Sˣ`](@ref S_x).
 """
 σˣ(args...; kwargs...) = 2 * S_x(args...; kwargs...)
 
@@ -177,7 +177,7 @@ const Sʸ = S_y
 """
 Pauli ``y`` operator, defined as ``σʸ = 2 ⋅ Sʸ``.
 
-See also [`Sʸ`](@ref).
+See also [`Sʸ`](@ref S_y).
 """
 σʸ(args...; kwargs...) = 2 * S_y(args...; kwargs...)
 
@@ -234,7 +234,7 @@ const Sᶻ = S_z
 """
 Pauli ``z`` operator, defined as ``σᶻ = 2 ⋅ Sᶻ``.
 
-See also [`Sᶻ`](@ref).
+See also [`Sᶻ`](@ref S_z).
 """
 σᶻ(args...; kwargs...) = 2 * S_z(args...; kwargs...)
 
@@ -299,7 +299,7 @@ const S⁺ = S_plus
 """
 Pauli plus operator, defined as ``σ⁺ = 2 ⋅ S⁺``.
 
-See also [`S⁺`](@ref).
+See also [`S⁺`](@ref S_plus).
 """
 σ⁺(args...; kwargs...) = 2 * S_plus(args...; kwargs...)
 
@@ -364,7 +364,7 @@ const S⁻ = S_min
 """
 Pauli minus operator, defined as ``σ⁻ = 2 ⋅ S⁻``.
 
-See also [`S⁻`](@ref).
+See also [`S⁻`](@ref S_min).
 """
 σ⁻(args...; kwargs...) = 2 * S_min(args...; kwargs...)
 
@@ -372,8 +372,8 @@ unicode_table = Dict(:x => :ˣ, :y => :ʸ, :z => :ᶻ, :plus => :⁺, :min => :
 
 function spinop_docstring(L::Symbol, R::Symbol)
     return """
-    S_$L$R([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
-    $(Symbol(:S, unicode_table[L], unicode_table[R]))([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
+        S_$L$R([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
+        $(Symbol(:S, unicode_table[L], unicode_table[R]))([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; spin=1 // 2)
 
     The spin $L$R exchange operator.
 
@@ -381,12 +381,11 @@ function spinop_docstring(L::Symbol, R::Symbol)
     """
 end
 function pauli_unicode_docstring(L::Symbol, R::Symbol)
-    doc = """
+    return """
     Pauli $L$R operator, defined as ``σ$(unicode_table[L])$(unicode_table[R]) = 4 ⋅ S$(unicode_table[L])$(unicode_table[R])``.
 
-    See also [`S$(unicode_table[L])$(unicode_table[R])`](@ref).
+    See also [`S$(unicode_table[L])$(unicode_table[R])`](@ref S_$L$R).
     """
-    return doc
 end
 
 for (L, R) in ((:x, :x), (:y, :y), (:z, :z), (:plus, :min), (:min, :plus))
@@ -465,7 +464,7 @@ const SS = S_exchange
 """
 Pauli exchange operator, defined as ``σσ = 4 ⋅ SS``.
 
-See also [`SS`](@ref).
+See also [`SS`](@ref S_exchange).
 """
 σσ(args...; kwargs...) = 4 * S_exchange(args...; kwargs...)