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/task/compare.jl

@@ -1,11 +1,26 @@
+"""
+    ==(t1::AbstractTask, t2::AbstractTask)
+
+Fallback implementation of equality comparison between two abstract tasks. Always returns false. For equal specific types of t1 and t2, a more specific comparison is called instead, doing an actual comparison.
+"""
 function ==(t1::AbstractTask, t2::AbstractTask)
     return false
 end
 
+"""
+    ==(t1::AbstractComputeTask, t2::AbstractComputeTask)
+
+Equality comparison between two compute tasks.
+"""
 function ==(t1::AbstractComputeTask, t2::AbstractComputeTask)
     return typeof(t1) == typeof(t2)
 end
 
+"""
+    ==(t1::AbstractDataTask, t2::AbstractDataTask)
+
+Equality comparison between two data tasks.
+"""
 function ==(t1::AbstractDataTask, t2::AbstractDataTask)
     return data(t1) == data(t2)
 end

src/task/create.jl

@@ -0,0 +1,14 @@
+"""
+    copy(t::AbstractDataTask)
+
+Fallback implementation of the copy of an abstract data task, throwing an error.
+"""
+copy(t::AbstractDataTask) =
+    error("Need to implement copying for your data tasks!")
+
+"""
+    copy(t::AbstractComputeTask)
+
+Return a copy of the given compute task.
+"""
+copy(t::AbstractComputeTask) = typeof(t)()

src/task/print.jl

@@ -1,3 +1,8 @@
+"""
+    show(io::IO, t::FusedComputeTask)
+    
+Print a string representation of the fused compute task to io.
+"""
 function show(io::IO, t::FusedComputeTask)
     (T1, T2) = get_types(t)
     return print(io, "ComputeFuse(", T1(), ", ", T2(), ")")

src/task/properties.jl

@@ -1,22 +1,64 @@
+"""
+    compute(t::AbstractTask; data...)
+
+Fallback implementation of the compute function of a compute task, throwing an error.
+"""
 function compute(t::AbstractTask; data...)
     return error("Need to implement compute()")
 end
 
+"""
+    compute_effort(t::AbstractTask)
+
+Fallback implementation of the compute effort of a task, throwing an error.
+"""
 function compute_effort(t::AbstractTask)
     # default implementation using compute
     return error("Need to implement compute_effort()")
 end
 
+"""
+    data(t::AbstractTask)
+
+Fallback implementation of the data of a task, throwing an error.
+"""
 function data(t::AbstractTask)
     return error("Need to implement data()")
 end
 
+"""
+    compute_effort(t::AbstractDataTask)
+
+Return the compute effort of a data task, always zero, regardless of the specific task.
+"""
 compute_effort(t::AbstractDataTask) = 0
+
+"""
+    compute(t::AbstractDataTask; data...)
+
+The compute function of a data task, always the identity function, regardless of the specific task.
+"""
 compute(t::AbstractDataTask; data...) = data
+
+"""
+    data(t::AbstractDataTask)
+
+Return the data of a data task. Given by the task's `.data` field.
+"""
 data(t::AbstractDataTask) = getfield(t, :data)
 
+"""
+    data(t::AbstractComputeTask)
+
+Return the data of a compute task, always zero, regardless of the specific task.
+"""
 data(t::AbstractComputeTask) = 0
 
+"""
+    compute_effort(t::FusedComputeTask)
+
+Return the compute effort of a fused compute task. 
+"""
 function compute_effort(t::FusedComputeTask)
     (T1, T2) = collect(typeof(t).parameters)
     return compute_effort(T1()) + compute_effort(T2())
@@ -25,9 +67,9 @@ end
 # actual compute functions for the tasks can stay undefined for now
 # compute(t::ComputeTaskU, data::Any) = mycomputation(data)
 
-function compute_intensity(t::AbstractTask)::UInt64
-    if data(t) == 0
-        return typemax(UInt64)
-    end
-    return compute_effort(t) / data(t)
-end
+"""
+    get_types(::FusedComputeTask{T1, T2})
+
+Return a tuple of a the fused compute task's components' types.
+"""
+get_types(::FusedComputeTask{T1, T2}) where {T1, T2} = (T1, T2)

src/task/type.jl

@@ -1,13 +1,30 @@
+"""
+    AbstractTask
+
+The shared base type for any task.
+"""
 abstract type AbstractTask end
 
+"""
+    AbstractComputeTask <: AbstractTask
+
+The shared base type for any compute task.
+"""
 abstract type AbstractComputeTask <: AbstractTask end
+
+"""
+    AbstractDataTask <: AbstractTask
+
+The shared base type for any data task.
+"""
 abstract type AbstractDataTask <: AbstractTask end
 
+"""
+    FusedComputeTask{T1 <: AbstractComputeTask, T2 <: AbstractComputeTask} <: AbstractComputeTask
+
+A fused compute task made up of the computation of first `T1` and then `T2`.
+
+Also see: [`get_types`](@ref).
+"""
 struct FusedComputeTask{T1 <: AbstractComputeTask, T2 <: AbstractComputeTask} <:
        AbstractComputeTask end
-
-get_types(::FusedComputeTask{T1, T2}) where {T1, T2} = (T1, T2)
-
-copy(t::AbstractDataTask) =
-    error("Need to implement copying for your data tasks!")
-copy(t::AbstractComputeTask) = typeof(t)()