Add documentation to every function and automatic doc html building (#6)

Reviewed-on: Rubydragon/MetagraphOptimization.jl#6
Co-authored-by: Anton Reinhard <anton.reinhard@proton.me>
Co-committed-by: Anton Reinhard <anton.reinhard@proton.me>

src/models/abc/parse.jl

@@ -1,11 +1,14 @@
-using Printf
-
 # functions for importing DAGs from a file
 regex_a = r"^[A-C]\d+$"                     # Regex for the initial particles
 regex_c = r"^[A-C]\(([^']*),([^']*)\)$"     # Regex for the combinations of 2 particles
 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 +16,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 +28,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")
 
@@ -63,9 +77,11 @@ function parse_abc(filename::String, verbose::Bool = false)
         noNodes += 1
         if (noNodes % 100 == 0)
             if (verbose)
-                @printf "\rReading Nodes... %.2f%%" (
-                    100.0 * noNodes / nodesToRead
+                percent = string(
+                    round(100.0 * noNodes / nodesToRead, digits = 2),
+                    "%",
                 )
+                print("\rReading Nodes... $percent")
             end
         end
         if occursin(regex_a, node)

src/models/abc/properties.jl

@@ -1,21 +1,102 @@
-# define compute_efforts tasks computation
-# put some "random" numbers here for now
+"""
+    compute_effort(t::ComputeTaskS1)
+
+Return the compute effort of an S1 task.
+"""
 compute_effort(t::ComputeTaskS1) = 10
+
+"""
+    compute_effort(t::ComputeTaskS2)
+
+Return the compute effort of an S2 task.
+"""
 compute_effort(t::ComputeTaskS2) = 10
+
+"""
+    compute_effort(t::ComputeTaskU)
+
+Return the compute effort of a U task.
+"""
 compute_effort(t::ComputeTaskU) = 6
+
+"""
+    compute_effort(t::ComputeTaskV)
+
+Return the compute effort of a V task.
+"""
 compute_effort(t::ComputeTaskV) = 20
+
+"""
+    compute_effort(t::ComputeTaskP)
+
+Return the compute effort of a P task.
+"""
 compute_effort(t::ComputeTaskP) = 15
+
+"""
+    compute_effort(t::ComputeTaskSum)
+
+Return the compute effort of a Sum task. 
+
+Note: This is a constant compute effort, even though sum scales with the number of its inputs. Since there is only ever a single sum node in a graph generated from the ABC-Model,
+this doesn't matter.
+"""
 compute_effort(t::ComputeTaskSum) = 1
 
+"""
+    show(io::IO, t::DataTask)
+
+Print the data task to io.
+"""
 function show(io::IO, t::DataTask)
     return print(io, "Data", t.data)
 end
 
+"""
+    show(io::IO, t::ComputeTaskS1)
+
+Print the S1 task to io.
+"""
 show(io::IO, t::ComputeTaskS1) = print("ComputeS1")
+
+"""
+    show(io::IO, t::ComputeTaskS2)
+
+Print the S2 task to io.
+"""
 show(io::IO, t::ComputeTaskS2) = print("ComputeS2")
+
+"""
+    show(io::IO, t::ComputeTaskP)
+
+Print the P task to io.
+"""
 show(io::IO, t::ComputeTaskP) = print("ComputeP")
+
+"""
+    show(io::IO, t::ComputeTaskU)
+
+Print the U task to io.
+"""
 show(io::IO, t::ComputeTaskU) = print("ComputeU")
+
+"""
+    show(io::IO, t::ComputeTaskV)
+
+Print the V task to io.
+"""
 show(io::IO, t::ComputeTaskV) = print("ComputeV")
+
+"""
+    show(io::IO, t::ComputeTaskSum)
+
+Print the sum task to io.
+"""
 show(io::IO, t::ComputeTaskSum) = print("ComputeSum")
 
+"""
+    copy(t::DataTask)
+
+Copy the data task and return it.
+"""
 copy(t::DataTask) = DataTask(t.data)

src/models/abc/types.jl

@@ -1,25 +1,59 @@
+"""
+    DataTask <: AbstractDataTask
+
+Task representing a specific data transfer in the ABC Model.
+"""
 struct DataTask <: AbstractDataTask
     data::UInt64
 end
 
-# S task with 1 child
+"""
+    ComputeTaskS1 <: AbstractComputeTask
+
+S task with a single child.
+"""
 struct ComputeTaskS1 <: AbstractComputeTask end
 
-# S task with 2 children
+"""
+    ComputeTaskS2 <: AbstractComputeTask
+
+S task with two children.
+"""
 struct ComputeTaskS2 <: AbstractComputeTask end
 
-# P task with 0 children
+"""
+    ComputeTaskP <: AbstractComputeTask
+
+P task with no children.
+"""
 struct ComputeTaskP <: AbstractComputeTask end
 
-# v task with 2 children
+"""
+    ComputeTaskV <: AbstractComputeTask
+
+v task with two children.
+"""
 struct ComputeTaskV <: AbstractComputeTask end
 
-# u task with 1 child
+"""
+    ComputeTaskU <: AbstractComputeTask
+
+u task with a single child.
+"""
 struct ComputeTaskU <: AbstractComputeTask end
 
-# task that sums all its inputs, n children
+"""
+    ComputeTaskSum <: AbstractComputeTask
+
+Task that sums all its inputs, n children.
+"""
 struct ComputeTaskSum <: AbstractComputeTask end
 
+"""
+    ABC_TASKS
+
+Constant vector of all tasks of the ABC-Model.
+"""
 ABC_TASKS = [
     DataTask,
     ComputeTaskS1,