Documenting the core APIs.

Author: rcschrg

src/algorithm/core.jl

@@ -1,17 +1,76 @@
 export DistributedAlgorithm, on_exchange_message, CoordinatedDistributedAlgorithm, start_optimization, Coordinator
 
+"""
+    DistributedAlgorithm
+
+An abstract type representing the base for distributed optimization algorithms.
+Subtypes should implement specific distributed algorithm logic for resource optimization.
+"""
 abstract type DistributedAlgorithm end
 
+
+"""
+    on_exchange_message(algorithm::DistributedAlgorithm, carrier::Carrier, message_data::Any, meta::Any)
+
+Handles an incoming exchange message within the distributed algorithm framework.
+
+# Arguments
+- `algorithm::DistributedAlgorithm`: The distributed algorithm instance managing the exchange.
+- `carrier::Carrier`: The communication carrier responsible for message delivery.
+- `message_data::Any`: The data contained in the received message.
+- `meta::Any`: Additional metadata associated with the message.
+
+# Description
+Processes the received exchange message, updating the algorithm's state or triggering appropriate actions based on the message content and metadata.
+
+# Returns
+May return a result or perform side effects depending on the implementation.
+"""
 function on_exchange_message(algorithm::DistributedAlgorithm, carrier::Carrier, message_data::Any, meta::Any)
     throw("NotImplementedOrWrongArgumentTypes")
 end
 
+
+"""
+    Coordinator
+
+An abstract type representing the coordinator in distributed resource optimization algorithms.
+Concrete implementations of this type are responsible for managing and coordinating the optimization process across distributed resources.
+"""
 abstract type Coordinator end
 
+
+"""
+    start_optimization(coordinator::Coordinator, carrier::Carrier, message_data::Any, meta::Any)
+
+Initiates the optimization process using the provided `coordinator` and `carrier` objects. 
+The function takes arbitrary `message_data` and `meta` information to configure or inform the optimization run.
+
+# Arguments
+- `coordinator::Coordinator`: The main coordinator responsible for managing the optimization workflow.
+- `carrier::Carrier`: The carrier object that facilitates communication or data transfer during optimization.
+- `message_data::Any`: Additional data or messages required for the optimization process.
+- `meta::Any`: Communication Metadata or supplementary information relevant to the optimization.
+
+# Returns
+- The result of the optimization process, which may vary depending on the implementation.
+
+# Notes
+- Ensure that `coordinator` and `carrier` are properly initialized before calling this function.
+- The types of `message_data` and `meta` are flexible to accommodate various use cases.
+"""
 function start_optimization(coordinator::Coordinator, carrier::Carrier, message_data::Any, meta::Any)
     throw("NotImplementedOrWrongArgumentTypes")
 end
 
+
+"""
+    CoordinatedDistributedAlgorithm
+
+A struct representing the core of a coordinated distributed optimization algorithm.
+This type encapsulates the necessary data and methods for coordinating multiple agents
+or processes in a distributed resource optimization setting.
+"""
 struct CoordinatedDistributedAlgorithm 
     distributed_algo::Vector{DistributedAlgorithm}
     coordinator::Coordinator

src/carrier/core.jl

@@ -1,25 +1,138 @@
 export Carrier, send_to_other, reply_to_other, send_and_wait_for_answers, send_awaitable, schedule_using, others
 
+"""
+    Carrier
+
+An abstract type representing a generic data/communication carrier in the system.
+Concrete subtypes should implement specific carrier behaviors and properties.
+"""
 abstract type Carrier end
 
+"""
+    send_to_other(carrier::Carrier, content_data::Any, receiver::Any)
+
+Sends `content_data` using the specified `carrier` to the given `receiver`.
+
+# Arguments
+- `carrier::Carrier`: The carrier object responsible for sending the data.
+- `content_data::Any`: The data to be sent.
+- `receiver::Any`: The target receiver of the data.
+
+# Returns
+- The result of the send operation, which may vary depending on the implementation.
+
+"""
 function send_to_other(carrier::Carrier, content_data::Any, receiver::Any)
     throw("NotImplemented")
 end
+
+
+"""
+    reply_to_other(carrier::Carrier, content_data::Any, meta::Any)
+
+Reply using the given `carrier` to another entity, using the provided `content_data` and 
+`meta` information.
+
+# Arguments
+- `carrier::Carrier`: The carrier object responsible for communication.
+- `content_data::Any`: The data to be sent in the reply.
+- `meta::Any`: Additional metadata associated with the reply.
+
+# Returns
+- The result of the reply operation, depending on the implementation.
+
+# Notes
+- The specific behavior depends on the implementation details of the `Carrier` type.
+"""
 function reply_to_other(carrier::Carrier, content_data::Any, meta::Any)
     throw("NotImplemented")
 end
+
+
+"""
+    send_and_wait_for_answers(carrier::Carrier, content_data::Any, receivers::Any)
+
+Sends `content_data` using `carrier` to the given `receivers` and waits for their responses.
+
+# Arguments
+- `carrier::Carrier`: The carrier object responsible for sending the data.
+- `content_data::Any`: The data to be sent to the receivers.
+- `receivers::Any`: The target receivers to which the data will be sent.
+
+# Returns
+Returns the responses received from the receivers after sending the data.
+
+# Notes
+This function blocks execution until all expected answers are received from the receivers.
+"""
 function send_and_wait_for_answers(carrier::Carrier, content_data::Any, receivers::Any)
     throw("NotImplemented")
 end
+
+
+"""
+    send_awaitable(carrier::Carrier, content_data::Any, receiver::Any)
+
+Sends an awaitable message using the specified `carrier` to the given `receiver` with the provided `content_data`.
+
+# Arguments
+- `carrier::Carrier`: The carrier object responsible for message transmission.
+- `content_data::Any`: The data to be sent in the message.
+- `receiver::Any`: The target recipient of the message.
+
+# Returns
+Returns an awaitable object or handle that can be used to track the completion or response of the sent message.
+"""
 function send_awaitable(carrier::Carrier, content_data::Any, receiver::Any)
     throw("NotImplemented $carrier $content_data $receiver")
 end
+
+"""
+    Base.wait(carrier::Carrier, waitable::Any)
+
+Waits for the specified `waitable` object to become ready or complete within the context of the given `carrier`. 
+This function integrates with the `Carrier`'s scheduling or resource management logic to handle asynchronous or blocking operations.
+
+# Arguments
+- `carrier::Carrier`: The carrier instance managing the waiting operation.
+- `waitable::Any`: The object or resource to wait for. This can be any type that supports waiting semantics.
+
+# Notes
+The function blocks until the `waitable` is ready or the operation is complete.
+"""
 function Base.wait(carrier::Carrier, waitable::Any)
     throw("NotImplemented")
 end
+
+"""
+    schedule_using(carrier::Carrier, to_be_scheduled::Function, delay_s::Float64)
+
+Schedules the execution of the provided function `to_be_scheduled` using the specified `carrier` after a delay of `delay_s` seconds.
+
+# Arguments
+- `carrier::Carrier`: The carrier object responsible for scheduling.
+- `to_be_scheduled::Function`: The function to be executed after the delay.
+- `delay_s::Float64`: The delay in seconds before executing the function.
+
+# Returns
+- Implementation-dependent. Typically, returns a handle or status indicating the scheduled task.
+"""
 function schedule_using(carrier::Carrier, to_be_scheduled::Function, delay_s::Float64)
     throw("NotImplemented")
 end
+
+"""
+    others(carrier::Carrier, participant_id::String)
+
+Returns a collection of participants in the given `carrier` excluding the participant with the specified `participant_id`.
+
+# Arguments
+- `carrier::Carrier`: The carrier object containing participants.
+- `participant_id::String`: The identifier of the participant to exclude.
+
+# Returns
+- A collection (e.g., array or set) of participants other than the one with `participant_id`.
+"""
 function others(carrier::Carrier, participant_id::String)
     throw("NotImplemented")
 end

src/carrier/mango.jl

@@ -2,6 +2,12 @@ export DistributedOptimizationRole, MangoCarrier, CoordinatorRole, StartCoordina
 
 using Mango
 
+"""
+    MangoCarrier <: Carrier
+
+A concrete implementation of the `Carrier` type representing a mango carrier.
+Extend this struct with relevant fields and methods to model the behavior and properties of a mango carrier in the distributed resource optimization context.
+"""
 struct MangoCarrier <: Carrier
     parent::Role
     include_self::Bool
@@ -11,17 +17,42 @@ struct StartCoordinatedDistributedOptimization
     input::Any
 end
 
+"""
+    OptimizationFinishedMessage
+
+A message struct indicating that an optimization process has completed.
+Typically used for signaling the end of an optimization routine in distributed or parallel computation contexts.
+"""
 struct OptimizationFinishedMessage 
     result::Any
 end
 
+"""
+    CoordinatorRole
+
+A role struct representing the coordinator in the distributed resource optimization system.
+Used to identify and manage coordinator-specific logic and responsibilities within the carrier module.
+"""
 @role struct CoordinatorRole
     coordinator::Coordinator
     carrier::Union{Nothing,MangoCarrier}
     tid::Symbol = :default
     task::Any = nothing
 end
 
+"""
+    CoordinatorRole(coordinator::Coordinator; include_self=false, tid::Symbol = :default)
+
+Assigns the coordinator role to the specified `coordinator` object. 
+
+# Arguments
+- `coordinator::Coordinator`: The coordinator instance to assign the role to.
+- `include_self::Bool=false`: If `true`, includes the coordinator itself in the role assignment.
+- `tid::Symbol=:default`: An optional identifier symbol for neighbor lookups.
+
+# Returns
+Returns the configured coordinator role.
+"""
 function CoordinatorRole(coordinator::Coordinator; include_self=false, tid::Symbol = :default)
     role = CoordinatorRole(coordinator, nothing, tid=tid)
     role.carrier = MangoCarrier(role, include_self)
@@ -38,12 +69,33 @@ function Mango.handle_message(role::CoordinatorRole, message::StartCoordinatedDi
     end
 end
 
+
+"""
+    DistributedOptimizationRole
+
+A role struct used to define distributed optimization responsibilities within the system.
+Attach this role to entities that participate in distributed resource optimization processes.
+"""
 @role struct DistributedOptimizationRole
     algorithm::DistributedAlgorithm
     carrier::Union{Nothing,MangoCarrier}
     tid::Symbol = :default
 end
 
+"""
+    DistributedOptimizationRole(algorithm::DistributedAlgorithm; tid::Symbol = :default)
+
+Creates and returns a distributed optimization role using the specified `algorithm`. 
+An optional identifier `tid` can be provided, defaulting to `:default`.
+
+# Arguments
+- `algorithm::DistributedAlgorithm`: The distributed optimization algorithm to be used.
+- `tid::Symbol`: (Optional) Identifier for the neighbor lookup. Defaults to `:default`.
+
+# Returns
+A distributed optimization role configured with the given algorithm and an identifier
+to specify the addresses of other participants.
+"""
 function DistributedOptimizationRole(algorithm::DistributedAlgorithm; tid::Symbol = :default)
     role = DistributedOptimizationRole(algorithm, nothing, tid=tid)
     role.carrier = MangoCarrier(role, false)