Continue documenting

src/graph/mute.jl

@@ -179,12 +179,24 @@ function remove_edge!(
     return nothing
 end
 
-# return the graph "difference" since last time this function was called
+"""
+    get_snapshot_diff(graph::DAG)
+
+Return the graph's [`Diff`](@ref) since last time this function was called.
+
+See also: [`revert_diff`](@ref), [`AppliedOperation`](@ref) and [`revert_operation`](@ref)
+"""
 function get_snapshot_diff(graph::DAG)
     return swapfield!(graph, :diff, Diff())
 end
 
-# function to invalidate the operation caches for a given NodeFusion
+"""
+    invalidate_caches!(graph::DAG, operation::NodeFusion)
+
+Invalidate the operation caches for a given [`NodeFusion`](@ref).
+
+This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
+"""
 function invalidate_caches!(graph::DAG, operation::NodeFusion)
     delete!(graph.possibleOperations, operation)
 
@@ -197,7 +209,13 @@ function invalidate_caches!(graph::DAG, operation::NodeFusion)
     return nothing
 end
 
-# function to invalidate the operation caches for a given NodeReduction
+"""
+    invalidate_caches!(graph::DAG, operation::NodeReduction)
+
+Invalidate the operation caches for a given [`NodeReduction`](@ref).
+
+This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
+"""
 function invalidate_caches!(graph::DAG, operation::NodeReduction)
     delete!(graph.possibleOperations, operation)
 
@@ -208,7 +226,13 @@ function invalidate_caches!(graph::DAG, operation::NodeReduction)
     return nothing
 end
 
-# function to invalidate the operation caches for a given NodeSplit
+"""
+    invalidate_caches!(graph::DAG, operation::NodeSplit)
+
+Invalidate the operation caches for a given [`NodeSplit`](@ref).
+
+This deletes the operation from the graph's possible operations and from the involved nodes' own operation caches.
+"""
 function invalidate_caches!(graph::DAG, operation::NodeSplit)
     delete!(graph.possibleOperations, operation)
 
@@ -219,7 +243,11 @@ function invalidate_caches!(graph::DAG, operation::NodeSplit)
     return nothing
 end
 
-# function to invalidate the operation caches of a ComputeTaskNode
+"""
+    invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
+
+Invalidate the operation caches of the given node through calls to the respective [`invalidate_caches!`](@ref) functions.
+"""
 function invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
     if !ismissing(node.nodeReduction)
         invalidate_caches!(graph, node.nodeReduction)
@@ -233,7 +261,11 @@ function invalidate_operation_caches!(graph::DAG, node::ComputeTaskNode)
     return nothing
 end
 
-# function to invalidate the operation caches of a DataTaskNode
+"""
+    invalidate_operation_caches!(graph::DAG, node::DataTaskNode)
+
+Invalidate the operation caches of the given node through calls to the respective [`invalidate_caches!`](@ref) functions.
+"""
 function invalidate_operation_caches!(graph::DAG, node::DataTaskNode)
     if !ismissing(node.nodeReduction)
         invalidate_caches!(graph, node.nodeReduction)

src/graph/print.jl

@@ -1,4 +1,9 @@
-function show_nodes(io, graph::DAG)
+"""
+    show_nodes(io::IO, graph::DAG)
+
+Print a graph's nodes. Should only be used for small graphs as it prints every node in a list.
+"""
+function show_nodes(io::IO, graph::DAG)
     print(io, "[")
     first = true
     for n in graph.nodes
@@ -12,6 +17,11 @@ function show_nodes(io, graph::DAG)
     return print(io, "]")
 end
 
+"""
+    show(io::IO, graph::DAG)
+
+Print the given graph to io. If there are too many nodes it will print only a summary of them.
+"""
 function show(io::IO, graph::DAG)
     println(io, "Graph:")
     print(io, "  Nodes: ")

src/graph/properties.jl

@@ -1,3 +1,8 @@
+"""
+    graph_properties(graph::DAG)
+
+Return the graph's properties, a named tuple with fields `.data`, `.compute_effort`, `.compute_intensity`, `.nodes` (number of nodes) and `.edges` (number of edges).
+"""
 function graph_properties(graph::DAG)
     # make sure the graph is fully generated
     apply_all!(graph)
@@ -23,6 +28,11 @@ function graph_properties(graph::DAG)
     return result
 end
 
+"""
+    get_exit_node(graph::DAG)
+
+Return the graph's exit node. This assumes the graph only has a single exit node. If the graph has multiple exit nodes, the one encountered first will be returned.
+"""
 function get_exit_node(graph::DAG)
     for node in graph.nodes
         if (is_exit_node(node))

src/graph/type.jl

@@ -15,9 +15,10 @@ end
 """ 
     DAG
 
-The DAG is the representation of the graph as a set of nodes.
+The representation of the graph as a set of [`Node`](@ref)s.
 
 A DAG can be loaded using the appropriate parse function, e.g. [`parse_abc`](@ref).
+
 [`Operation`](@ref)s can be applied on it using [`push_operation!`](@ref) and reverted using [`pop_operation!`](@ref) like a stack.
 To get the set of possible operations, use [`get_operations`](@ref).
 The members of the object should not be manually accessed, instead always use the provided interface functions.
@@ -42,6 +43,11 @@ mutable struct DAG
     diff::Diff
 end
 
+"""
+    PossibleOperations()
+
+Construct and return an empty [`PossibleOperations`](@ref) object.
+"""
 function PossibleOperations()
     return PossibleOperations(
         Set{NodeFusion}(),
@@ -50,6 +56,11 @@ function PossibleOperations()
     )
 end
 
+"""
+    DAG()
+
+Construct and return an empty [`DAG`](@ref).
+"""
 function DAG()
     return DAG(
         Set{Node}(),

src/graph/validate.jl

@@ -1,4 +1,8 @@
-# check whether the given graph is connected
+"""
+    is_connected(graph::DAG)
+
+Return whether the given graph is connected.
+"""
 function is_connected(graph::DAG)
     nodeQueue = Deque{Node}()
     push!(nodeQueue, get_exit_node(graph))
@@ -16,6 +20,11 @@ function is_connected(graph::DAG)
     return length(seenNodes) == length(graph.nodes)
 end
 
+"""
+    is_valid(graph::DAG)
+
+Validate the entire graph using asserts. Intended for testing with `@assert is_valid(graph)`.
+"""
 function is_valid(graph::DAG)
     for node in graph.nodes
         @assert is_valid(graph, node)

src/models/abc/parse.jl

@@ -6,6 +6,11 @@ regex_c = r"^[A-C]\(([^']*),([^']*)\)$"     # Regex for the combinations of 2 pa
 regex_m = r"^M\(([^']*),([^']*),([^']*)\)$" # Regex for the combinations of 3 particles
 regex_plus = r"^\+$"                        # Regex for the sum
 
+"""
+    parse_nodes(input::AbstractString)
+
+Parse the given string into a vector of strings containing each node.
+"""
 function parse_nodes(input::AbstractString)
     regex = r"'([^']*)'"
     matches = eachmatch(regex, input)
@@ -13,6 +18,11 @@ function parse_nodes(input::AbstractString)
     return output
 end
 
+"""
+    parse_edges(input::AbstractString)
+
+Parse the given string into a vector of strings containing each edge. Currently unused since the entire graph can be read from just the node names.
+"""
 function parse_edges(input::AbstractString)
     regex = r"\('([^']*)', '([^']*)'\)"
     matches = eachmatch(regex, input)
@@ -20,7 +30,13 @@ function parse_edges(input::AbstractString)
     return output
 end
 
-# reads an abc-model process from the given file
+"""
+    parse_abc(filename::String; verbose::Bool = false)
+
+Read an abc-model process from the given file. If `verbose` is set to true, print some progress information to stdout.
+
+Returns a valid [`DAG`](@ref).
+"""
 function parse_abc(filename::String, verbose::Bool = false)
     file = open(filename, "r")