From 4c1ec371640e786a2cf333f9bd51828530a2d3af Mon Sep 17 00:00:00 2001 From: Neven Sajko Date: Tue, 7 Oct 2025 15:38:07 +0200 Subject: [PATCH 1/3] add doc string to each exported binding Also add some properties. --- src/GraphProperties.jl | 168 +++++++++++++++++++++++------------------ 1 file changed, 96 insertions(+), 72 deletions(-) diff --git a/src/GraphProperties.jl b/src/GraphProperties.jl index b26ebb0..14e7315 100644 --- a/src/GraphProperties.jl +++ b/src/GraphProperties.jl @@ -4,8 +4,20 @@ export GraphProperty, PropertyComparison +""" + GraphProperty::Type + +Abstract supertype for graph properties. + +The only type parameter is the type of each value of the property. +""" abstract type GraphProperty{T} end +""" + PropertyComparison(comparison, property, value) + +Turn a `GraphProperty{<:Real}` into a `GraphProperty{Bool}` by attaching a comparison against a value. +""" struct PropertyComparison{ Comparison <: Union{typeof(==), typeof(≤)}, Property <: GraphProperty{<:Real}, @@ -17,76 +29,79 @@ struct PropertyComparison{ end let - properties_abstractvector = Symbol[ - :DegreeSequence, + properties_abstractvector = Tuple{Symbol, String}[ + (:DegreeSequence, "The *degree sequence* of an undirected graph."), ] - properties_real = Symbol[ - :FractionalChromaticNumber, - :FractionalMatchingNumber, + properties_real = Tuple{Symbol, String}[ + (:FractionalChromaticNumber, "The *fractional chromatic number* of an undirected graph."), + (:FractionalMatchingNumber, "The *fractional matching number* of an undirected graph."), + (:Strength, "The *strength* of an undirected graph."), ] - properties_integer = Symbol[ - :NumberOfVertices, - :NumberOfEdges, - :NumberOfArcs, - :NumberOfConnectedComponents, - :MinimumDegree, - :MaximumDegree, - :Girth, - :VertexConnectivity, - :EdgeConnectivity, - :CliqueNumber, - :ChromaticNumber, - :ChromaticIndex, - :MatchingNumber, - :DominationNumber, - :IndependenceNumber, - :Choosability, - :FeedbackVertexSetNumber, - :VertexCoverNumber, - :EdgeCoverNumber, - :IntersectionNumber, - :BipartiteDimension, - :HadwigerNumber, - :TwinWidth, - :CliqueWidth, - :Treewidth, - :Pathwidth, - :Boxicity, - :Degeneracy, - :Arboricity, - :Splittance, + properties_integer = Tuple{Symbol, String}[ + (:NumberOfVertices, "The *number of vertices* of a graph."), + (:NumberOfEdges, "The *number of edges* of an undirected graph."), + (:NumberOfArcs, "The *number of arcs* of a directed graph."), + (:NumberOfConnectedComponents, "The *number of connected components* of an undirected graph."), + (:MinimumDegree, "The *minimum degree* among the degrees of the vertices of an undirected graph."), + (:MaximumDegree, "The *maximum degree* among the degrees of the vertices of an undirected graph."), + (:Girth, "The *girth* of a undirected graph: the length of its shortest cycle."), + (:VertexConnectivity, "The *vertex-connectivity* of an undirected graph. Also known as the *connectivity*."), + (:EdgeConnectivity, "The *edge-connectivity* of an undirected graph."), + (:CliqueNumber, "The *clique number* of an undirected graph."), + (:ChromaticNumber, "The *chromatic number* of an undirected graph."), + (:ChromaticIndex, "The *chromatic index* of an undirected graph. Also known as the *edge chromatic number*."), + (:MatchingNumber, "The *matching number* of an undirected graph."), + (:DominationNumber, "The *domination number* of an undirected graph."), + (:StrongDominationNumber, "The *strong domination number* of an undirected graph."), + (:IndependenceNumber, "The *independence number* of an undirected graph."), + (:Choosability, "The *choosability* of an undirected graph. Also known as the *list colorability* or as the *list chromatic number*."), + (:FeedbackVertexSetNumber, "The *feedback vertex set number* of a graph."), + (:VertexCoverNumber, "The *vertex cover number* of an undirected graph."), + (:EdgeCoverNumber, "The *edge cover number* of an undirected graph."), + (:IntersectionNumber, "The *intersection number* of an undirected graph. Also known as the *R-content* or as the *edge clique cover number* or as the *clique cover number*."), + (:BipartiteDimension, "The *bipartite dimension* of an undirected graph. Also known as the *biclique cover number*."), + (:HadwigerNumber, "The *Hadwiger number* of an undirected graph. Also known as the *contraction clique number* or as the *homomorphism degree*."), + (:TwinWidth, "The *twin-width* of an undirected graph."), + (:CliqueWidth, "The *clique-width* of an undirected graph."), + (:Treewidth, "The *treewidth* of an undirected graph."), + (:Pathwidth, "The *pathwidth* of an undirected graph. Also known as the *interval thickness* or as the *vertex separation number* or as the *node searching number*."), + (:Boxicity, "The *boxicity* of an undirected graph."), + (:Sphericity, "The *sphericity* of an undirected graph."), + (:Degeneracy, "The *degeneracy* of an undirected graph. Also known as the *width* or as the *linkage*."), + (:Arboricity, "The *arboricity* of an undirected graph."), + (:Splittance, "The *splittance* of an undirected graph."), ] - properties_bool = Symbol[ - :IsUndirectedGraph, - :IsDirectedGraph, - :DigraphIsDAG, - :DigraphIsOrientation, - :GraphIsConnected, - :DigraphIsWeaklyConnected, - :DigraphIsStronglyConnected, - :GraphIsBipartite, - :GraphIsPath, - :GraphIsCycle, - :GraphIsPlanar, - :DigraphIsPlanar, - :GraphIsTriangleFree, - :GraphIsComplete, - :GraphIsRegular, - :GraphIsPerfect, - :GraphIsTriviallyPerfect, - :GraphIsForest, - :GraphIsTree, - :GraphIsIndifferenceGraph, - :GraphIsIntervalGraph, - :GraphIsPtolemaic, - :GraphIsChordal, - :GraphIsMeynielGraph, - :GraphIsCircleGraph, - :GraphIsPermutationGraph, - :GraphIsCograph, - :GraphIsComparabilityGraph, - :GraphIsDistanceHereditary, - :GraphIsSplitGraph, + properties_bool = Tuple{Symbol, String}[ + (:IsUndirectedGraph, "Is something an undirected graph?"), + (:IsDirectedGraph, "Is something a directed graph?"), + (:DigraphIsDAG, "Is a directed graph acyclic (a DAG)?"), + (:DigraphIsOrientation, "Is a directed graph an orientation?"), + (:GraphIsConnected, "Is an undirected graph connected?"), + (:DigraphIsWeaklyConnected, "Is a directed graph weakly connected?"), + (:DigraphIsStronglyConnected, "Is a directed graph strongly connected?"), + (:GraphIsBipartite, "Is an undirected graph bipartite?"), + (:GraphIsPath, "Is an undirected graph a path?"), + (:GraphIsCycle, "Is an undirected graph a cycle?"), + (:GraphIsPlanar, "Is an undirected graph planar?"), + (:DigraphIsPlanar, "Is a directed graph planar?"), + (:GraphIsTriangleFree, "Is an undirected graph triangle-free?"), + (:GraphIsComplete, "Is an undirected graph complete?"), + (:GraphIsRegular, "Is an undirected graph regular?"), + (:GraphIsPerfect, "Is an undirected graph perfect?"), + (:GraphIsTriviallyPerfect, "Is an undirected graph trivially perfect?"), + (:GraphIsForest, "Is an undirected graph a forest?"), + (:GraphIsTree, "Is an undirected graph a tree?"), + (:GraphIsIndifferenceGraph, "Is an undirected graph an indifference graph?"), + (:GraphIsIntervalGraph, "Is an undirected graph an interval graph?"), + (:GraphIsPtolemaic, "Is an undirected graph Ptolemaic?"), + (:GraphIsChordal, "Is an undirected graph chordal?"), + (:GraphIsMeynielGraph, "Is an undirected graph a Meyniel graph?"), + (:GraphIsCircleGraph, "Is an undirected graph a circle graph?"), + (:GraphIsPermutationGraph, "Is an undirected graph a permutation graph?"), + (:GraphIsCograph, "Is an undirected graph a cograph?"), + (:GraphIsComparabilityGraph, "Is an undirected graph a comparability graph?"), + (:GraphIsDistanceHereditary, "Is an undirected graph distance-hereditary?"), + (:GraphIsSplitGraph, "Is an undirected graph a split graph?"), ] for (typ, properties) ∈ ( (AbstractVector, properties_abstractvector), @@ -94,13 +109,22 @@ let (Integer, properties_integer), (Bool, properties_bool), ) - for p ∈ properties - @eval export $p - @eval struct $p <: GraphProperty{$typ} end + for (name, desc) ∈ properties + @eval export $name + @eval begin + """ + $($name)() + + $($desc) + + ```jldoctest + $($name)() isa GraphProperty{$($typ)} + ``` + """ + struct $name <: GraphProperty{$typ} end + end end end end -# TODO: doc strings - end From 0356b6889d8ff8cfe52933fd5e9a19f5222b6738 Mon Sep 17 00:00:00 2001 From: Neven Sajko Date: Tue, 7 Oct 2025 18:44:47 +0200 Subject: [PATCH 2/3] fix doc tests --- src/GraphProperties.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GraphProperties.jl b/src/GraphProperties.jl index 14e7315..5a15146 100644 --- a/src/GraphProperties.jl +++ b/src/GraphProperties.jl @@ -118,7 +118,7 @@ let $($desc) ```jldoctest - $($name)() isa GraphProperty{$($typ)} + $($name)() isa GraphProperty{$($typ)} # true ``` """ struct $name <: GraphProperty{$typ} end From 02cc6eb5cc2d0fc1d5ed0fd841cc0df98e0bdcbd Mon Sep 17 00:00:00 2001 From: Neven Sajko Date: Tue, 7 Oct 2025 18:50:36 +0200 Subject: [PATCH 3/3] try fixing doc tests again --- src/GraphProperties.jl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/GraphProperties.jl b/src/GraphProperties.jl index 5a15146..eee8b99 100644 --- a/src/GraphProperties.jl +++ b/src/GraphProperties.jl @@ -118,7 +118,10 @@ let $($desc) ```jldoctest - $($name)() isa GraphProperty{$($typ)} # true + julia> using GraphProperties + + julia> $($name)() isa GraphProperty{$($typ)} + true ``` """ struct $name <: GraphProperty{$typ} end