polish docstrings

Author: ChenZhao44

src/ZX/circuit_extraction.jl

@@ -1,8 +1,14 @@
+using DocStringExtensions
+
 """
-    ancilla_extraction(zxg::ZXGraph) -> ZXDiagram
+    $(TYPEDSIGNATURES)
+
+Extract a quantum circuit from a general ZX-graph even without a gflow.
+
+This function can handle ZX-graphs that don't have a generalised flow (gflow),
+and will introduce post-selection operators as needed.
 
-Extract a quantum circuit from a general `ZXGraph` even without a gflow.
-It will introduce post-selection operators.
+Returns a `ZXDiagram` representing the extracted circuit.
 """
 function ancilla_extraction(zxg::Union{ZXGraph, ZXCircuit})
     nzxg = copy(zxg)
@@ -172,9 +178,14 @@ function update_frontier_ancilla!(frontiers, nzxg, gads, qubit_map, unextracts,
 end
 
 """
-    circuit_extraction(zxg::ZXGraph)
+    $(TYPEDSIGNATURES)
+
+Extract a quantum circuit from a graph-like ZX-diagram.
+
+This is the main circuit extraction algorithm that converts a ZX-diagram
+in graph-like form into an equivalent quantum circuit.
 
-Extract circuit from a graph-like ZX-diagram.
+Returns a `ZXDiagram` representing the extracted circuit.
 """
 function circuit_extraction(zxg::Union{ZXGraph{T, P}, ZXCircuit{T, P}}) where {T, P}
     nzxg = copy(zxg)

src/ZX/equality.jl

@@ -1,7 +1,15 @@
+using DocStringExtensions
+
 """
-    verify_equality(zxd_1::ZXDiagram, zxd_2::ZXDiagram)
+    $(TYPEDSIGNATURES)
+
+Check the equivalence of two different ZX-diagrams.
+
+This function concatenates the first diagram with the dagger of the second,
+then performs full reduction. If the result contains only bare wires, the
+diagrams are equivalent.
 
-checks the equivalence of two different ZXDiagrams
+Returns `true` if the diagrams are equivalent, `false` otherwise.
 """
 function verify_equality(zxd_1::ZXDiagram, zxd_2::ZXDiagram)
     merged_diagram = copy(zxd_1)

src/ZX/implementations/zx_circuit/type.jl

@@ -1,11 +1,30 @@
+using DocStringExtensions
+
+"""
+$(TYPEDEF)
+
+This is the type for representing ZX-circuits with explicit circuit structure.
+
+ZXCircuit separates the graph representation (ZXGraph) from circuit semantics
+(ordered inputs/outputs and layout). This design enables efficient graph-based
+simplification while maintaining circuit structure for extraction and visualization.
+
+# Fields
+$(TYPEDFIELDS)
+"""
 struct ZXCircuit{T, P} <: AbstractZXCircuit{T, P}
+    "The underlying ZXGraph representation"
     zx_graph::ZXGraph{T, P}
+    "Ordered input spider vertices"
     inputs::Vector{T}
+    "Ordered output spider vertices"
     outputs::Vector{T}
+    "Layout information for visualization"
     layout::ZXLayout{T}
 
-    # maps a vertex id to its master id and scalar multiplier
+    "Maps vertex id to its master id and scalar multiplier for phase tracking"
     phase_ids::Dict{T, Tuple{T, Int}}
+    "Reference to master circuit for phase tracking (optional)"
     master::Union{Nothing, ZXCircuit{T, P}}
 end
 

src/ZX/implementations/zx_diagram/type.jl

@@ -1,5 +1,7 @@
+using DocStringExtensions
+
 """
-    ZXDiagram{T, P}
+$(TYPEDEF)
 
 This is the type for representing ZX-diagrams.
 
@@ -10,18 +12,29 @@ This is the type for representing ZX-diagrams.
 
     `ZXCircuit` provides the same functionality with better separation of concerns
     and more efficient graph-based simplification algorithms.
+
+# Fields
+$(TYPEDFIELDS)
 """
 struct ZXDiagram{T <: Integer, P <: AbstractPhase} <: AbstractZXCircuit{T, P}
+    "The underlying multigraph structure"
     mg::Multigraph{T}
 
+    "Spider types indexed by vertex"
     st::Dict{T, SpiderType.SType}
+    "Phases of spiders indexed by vertex"
     ps::Dict{T, P}
 
+    "Layout information for visualization"
     layout::ZXLayout{T}
+    "Maps vertex id to its master id and scalar multiplier"
     phase_ids::Dict{T, Tuple{T, Int}}
 
+    "Global scalar factor"
     scalar::Scalar{P}
+    "Ordered input spider vertices"
     inputs::Vector{T}
+    "Ordered output spider vertices"
     outputs::Vector{T}
 
     function ZXDiagram{T, P}(

src/ZX/implementations/zx_graph/type.jl

@@ -1,17 +1,27 @@
+using DocStringExtensions
+
 """
-    ZXGraph{T, P}
+$(TYPEDEF)
 
 This is the type for representing the graph-like ZX-diagrams.
 
 A pure graph representation without circuit structure assumptions.
 Spiders of type In/Out can exist but are treated as searchable vertices,
 not as ordered inputs/outputs.
+
+# Fields
+$(TYPEDFIELDS)
 """
 struct ZXGraph{T <: Integer, P <: AbstractPhase} <: AbstractZXDiagram{T, P}
+    "The underlying multigraph structure"
     mg::Multigraph{T}
+    "Phases of spiders indexed by vertex"
     ps::Dict{T, P}
+    "Spider types indexed by vertex"
     st::Dict{T, SpiderType.SType}
+    "Edge types indexed by sorted vertex pairs"
     et::Dict{Tuple{T, T}, EdgeType.EType}
+    "Global scalar factor"
     scalar::Scalar{P}
 end
 

src/ZX/phase_teleportation.jl

@@ -1,7 +1,14 @@
+using DocStringExtensions
+
 """
-    phase_teleportation(zxd)
+    $(TYPEDSIGNATURES)
+
+Reduce T-count of `zxd` with the phase teleportation algorithms in [arXiv:1903.10477](https://arxiv.org/abs/1903.10477).
+
+This optimization technique reduces the number of non-Clifford (T) gates in the circuit
+by teleporting phases through the diagram.
 
-Reducing T-count of `zxd` with the algorithms in [arXiv:1903.10477](https://arxiv.org/abs/1903.10477).
+Returns a ZX-diagram with reduced T-count.
 """
 function phase_teleportation(cir::ZXDiagram{T, P}) where {T, P}
     zxg = ZXCircuit(cir; track_phase=true, normalize=true)

src/ZX/rules/interface.jl

@@ -1,3 +1,5 @@
+using DocStringExtensions
+
 abstract type AbstractRule end
 
 """
@@ -32,27 +34,35 @@ struct Rule{L} <: AbstractRule end
 Rule(r::Symbol) = Rule{r}()
 
 """
-    Match{T<:Integer}
+$(TYPEDEF)
+
+A struct for saving matched vertices from rule matching.
 
-A struct for saving matched vertices.
+# Fields
+$(TYPEDFIELDS)
 """
 struct Match{T <: Integer}
+    "Vector of vertex identifiers that match a rule pattern"
     vertices::Vector{T}
 end
 
 """
-    match(r, zxd)
+    $(TYPEDSIGNATURES)
+
+Find all vertices in ZX-diagram `zxd` that match the pattern of rule `r`.
 
-Returns all matched vertices, which will be stored in struct `Match`, for rule `r`
-in a ZX-diagram `zxd`.
+Returns a vector of `Match` objects containing the matched vertex sets.
 """
 Base.match(r::AbstractRule, ::AbstractZXDiagram{T, P}) where {T, P} = error("match not implemented for rule $(r)")
 
 """
-    rewrite!(r, zxd, matches)
+    $(TYPEDSIGNATURES)
+
+Rewrite a ZX-diagram `zxd` with rule `r` for all vertices in `matches`.
+
+The `matches` parameter can be a vector of `Match` objects or a single `Match` instance.
 
-Rewrite a ZX-diagram `zxd` with rule `r` for all vertices in `matches`. `matches`
-can be a vector of `Match` or just an instance of `Match`.
+Returns the modified ZX-diagram.
 """
 function rewrite!(r::AbstractRule, zxd::AbstractZXDiagram{T, P}, matches::Vector{Match{T}}) where {T, P}
     for each in matches
@@ -70,18 +80,27 @@ function rewrite!(r::AbstractRule, zxd::AbstractZXDiagram{T, P}, matched::Match{
 end
 
 """
-    rewrite!(r, zxd, vs)
+    $(TYPEDSIGNATURES)
 
-Rewrite a ZX-diagram `zxd` with rule `r` for vertices `vs`.
+Rewrite a ZX-diagram `zxd` with rule `r` for the specific vertices `vs`.
+
+This is the core rewriting function that must be implemented for each rule.
+
+Returns the modified ZX-diagram.
 """
 function rewrite!(r::AbstractRule, ::AbstractZXDiagram{T, P}, ::Vector{T}) where {T, P}
     return error("rewrite! not implemented for rule $(r)!")
 end
 
 """
-    check_rule(r, zxd, vs)
+    $(TYPEDSIGNATURES)
 
 Check whether the vertices `vs` in ZX-diagram `zxd` still match the rule `r`.
+
+This is used to verify that a previously matched pattern is still valid before rewriting,
+as the diagram may have changed since the match was found.
+
+Returns `true` if the vertices still match the rule pattern, `false` otherwise.
 """
 function check_rule(r::AbstractRule, ::AbstractZXDiagram{T, P}, ::Vector{T}) where {T, P}
     return error("check_rule not implemented for rule $(r)!")

src/ZX/simplify.jl

@@ -1,9 +1,13 @@
+using DocStringExtensions
+
 const MAX_ITERATION = Ref{Int}(1000)
 
 """
-    replace!(r, zxd)
+    $(TYPEDSIGNATURES)
 
 Match and replace with the rule `r`.
+
+Returns the modified ZX-diagram.
 """
 function Base.replace!(r::AbstractRule, zxd::AbstractZXDiagram)
     matches = match(r, zxd)
@@ -12,9 +16,13 @@ function Base.replace!(r::AbstractRule, zxd::AbstractZXDiagram)
 end
 
 """
-    simplify!(r, zxd)
+    $(TYPEDSIGNATURES)
 
 Simplify `zxd` with the rule `r`.
+
+Repeatedly applies the rule until no more matches are found or MAX_ITERATION is reached.
+
+Returns the simplified ZX-diagram.
 """
 function simplify!(r::AbstractRule, zxd::AbstractZXDiagram)
     i = 1
@@ -39,9 +47,14 @@ function to_z_form!(zxg::Union{ZXGraph, ZXCircuit})
 end
 
 """
-    clifford_simplification(zxd)
+    $(TYPEDSIGNATURES)
+
+Simplify `zxd` with the Clifford simplification algorithms in [arXiv:1902.03178](https://arxiv.org/abs/1902.03178).
+
+This applies a sequence of local complementation and pivot rules to simplify the ZX-diagram
+while preserving Clifford structure.
 
-Simplify `zxd` with the algorithms in [arXiv:1902.03178](https://arxiv.org/abs/1902.03178).
+Returns the simplified ZX-diagram.
 """
 function clifford_simplification(circ::ZXDiagram)
     zxg = ZXCircuit(circ; track_phase=true, normalize=true)

src/ZX/types/zx_layout.jl

@@ -1,11 +1,19 @@
+using DocStringExtensions
+
 """
-    ZXLayout
+$(TYPEDEF)
+
+A struct for the layout information of ZX-circuits.
 
-A struct for the layout information of `ZXDiagram` and `ZXGraph`.
+# Fields
+$(TYPEDFIELDS)
 """
 struct ZXLayout{T <: Integer}
+    "Number of qubits in the circuit"
     nbits::Int
+    "Mapping from spider vertices to qubit locations"
     spider_q::Dict{T, Rational{Int}}
+    "Mapping from spider vertices to column positions"
     spider_col::Dict{T, Rational{Int}}
 end
 
@@ -24,43 +32,43 @@ end
 nqubits(layout::ZXLayout) = layout.nbits
 
 """
-    qubit_loc(layout, v)
+    $(TYPEDSIGNATURES)
 
-Return the qubit number corresponding to the spider `v`.
+Return the qubit number corresponding to the spider `v`, or `nothing` if not in layout.
 """
 qubit_loc(layout::ZXLayout{T}, v::T) where T = get(layout.spider_q, v, nothing)
 
 """
-    column_loc(layout, v)
+    $(TYPEDSIGNATURES)
 
-Return the column number corresponding to the spider `v`.
+Return the column number corresponding to the spider `v`, or `nothing` if not in layout.
 """
 column_loc(layout::ZXLayout{T}, v::T) where T = get(layout.spider_col, v, nothing)
 
 """
-    set_qubit!(layout, v, q)
+    $(TYPEDSIGNATURES)
 
-Set the qubit number of the spider `v`.
+Set the qubit number of the spider `v` to `q`.
 """
 function set_qubit!(layout::ZXLayout{T}, v::T, q) where T
     layout.spider_q[v] = q
     return layout
 end
 
 """
-    set_qubit!(layout, v, q)
+    $(TYPEDSIGNATURES)
 
-Set the column number of the spider `v`.
+Set the column number of the spider `v` to `col`.
 """
 function set_column!(layout::ZXLayout{T}, v::T, col) where T
     layout.spider_col[v] = col
     return layout
 end
 
 """
-    set_loc!(layout, v, q, col)
+    $(TYPEDSIGNATURES)
 
-Set the location of the spider `v`.
+Set both the qubit and column location of the spider `v`.
 """
 function set_loc!(layout::ZXLayout{T}, v::T, q, col) where T
     set_qubit!(layout, v, q)