From 765a2a07bb981d4816022239d7fd8572df214284 Mon Sep 17 00:00:00 2001
From: Guillaume Binet <gbin@gootz.net>
Date: Mon, 3 Jun 2024 08:37:43 -0400
Subject: [PATCH] Preliminary documentation for the tasks

---
 copper/src/curuntime.rs    |  4 ++--
 copper/src/cutask.rs       | 33 +++++++++++++++++++++++++++++++--
 copper/src/monitoring.rs   |  4 ++--
 examples/v4lsrc/src/lib.rs |  4 ++--
 4 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/copper/src/curuntime.rs b/copper/src/curuntime.rs
index a5767fb19..9aac45198 100644
--- a/copper/src/curuntime.rs
+++ b/copper/src/curuntime.rs
@@ -60,8 +60,8 @@ mod tests {
     }
 
     impl CuSrcTask for TestSource {
-        type Payload = ();
-        fn process(&mut self, _empty_msg: &mut CuMsg<Self::Payload>) -> CuResult<()> {
+        type Output = ();
+        fn process(&mut self, _empty_msg: &mut CuMsg<Self::Output>) -> CuResult<()> {
             Ok(())
         }
     }
diff --git a/copper/src/cutask.rs b/copper/src/cutask.rs
index 9b3a51d3f..2c40e0cef 100644
--- a/copper/src/cutask.rs
+++ b/copper/src/cutask.rs
@@ -22,36 +22,60 @@ impl<T: CuMsgPayload> CuMsg<T> {
     }
 }
 
+/// The CuTaskLifecycle trait is the base trait for all tasks in Copper.
+/// It defines the lifecycle of a task.
+/// It provides a default empty implementation as all those execution steps are optional.
 pub trait CuTaskLifecycle {
     fn new(config: Option<&NodeInstanceConfig>) -> CuResult<Self>
     where
         Self: Sized;
 
+    /// Start is called once for a long period of time.
+    /// Here you need to initialize everything your task will need for the duration of its lifetime.
     fn start(&mut self) -> CuResult<()> {
         Ok(())
     }
 
+    /// This is a method called by the runtime before "process". This is a kind of best effort,
+    /// as soon as possible call to give a chance for the task to do some work before to prepare
+    /// to make "process" as short as possible.
     fn preprocess(&mut self) -> CuResult<()> {
         Ok(())
     }
 
+    /// This is a method called by the runtime after "process". It is best effort a chance for
+    /// the task to update some state after process is out of the way.
+    /// It can be use for example to maintain statistics etc. that are not time critical for the robot.
     fn postprocess(&mut self) -> CuResult<()> {
         Ok(())
     }
 
+    /// Call at the end of the lifecycle of the task.
     fn stop(&mut self) -> CuResult<()> {
         Ok(())
     }
 }
 
+/// A Src Task is a task that only produces messages. For example drivers for sensors are Src Tasks.
+/// They are in push mode from the runtime.
+/// To set the frequency of the pulls and align them to any hw, see the runtime configuration.
 pub trait CuSrcTask: CuTaskLifecycle {
-    type Payload: CuMsgPayload;
-    fn process(&mut self, empty_msg: &mut CuMsg<Self::Payload>) -> CuResult<()>;
+    type Output: CuMsgPayload;
+
+    /// Process is the most critical execution of the task.
+    /// The goal will be to produce the output message as soon as possible.
+    /// Use preprocess to prepare the task to make this method as short as possible.
+    fn process(&mut self, new_msg: &mut CuMsg<Self::Output>) -> CuResult<()>;
 }
 
+/// This is the most generic Task of copper. It is a "transform" task deriving an output from an input.
 pub trait CuTask: CuTaskLifecycle {
     type Input: CuMsgPayload;
     type Output: CuMsgPayload;
+
+    /// Process is the most critical execution of the task.
+    /// The goal will be to produce the output message as soon as possible.
+    /// Use preprocess to prepare the task to make this method as short as possible.
     fn process(
         &mut self,
         input: &CuMsg<Self::Input>,
@@ -59,7 +83,12 @@ pub trait CuTask: CuTaskLifecycle {
     ) -> CuResult<()>;
 }
 
+/// A Sink Task is a task that only consumes messages. For example drivers for actuators are Sink Tasks.
 pub trait CuSinkTask: CuTaskLifecycle {
     type Input: CuMsgPayload;
+
+    /// Process is the most critical execution of the task.
+    /// The goal will be to produce the output message as soon as possible.
+    /// Use preprocess to prepare the task to make this method as short as possible.
     fn process(&mut self, input: &CuMsg<Self::Input>) -> CuResult<()>;
 }
diff --git a/copper/src/monitoring.rs b/copper/src/monitoring.rs
index 22d2f4eed..c6b691e0a 100644
--- a/copper/src/monitoring.rs
+++ b/copper/src/monitoring.rs
@@ -100,9 +100,9 @@ impl CuTaskLifecycle for MonitoringTask {
 }
 
 impl CuSrcTask for MonitoringTask {
-    type Payload = ();
+    type Output = ();
 
-    fn process(&mut self, _empty_msg: &mut CuMsg<Self::Payload>) -> CuResult<()> {
+    fn process(&mut self, _empty_msg: &mut CuMsg<Self::Output>) -> CuResult<()> {
         Ok(())
     }
 }
diff --git a/examples/v4lsrc/src/lib.rs b/examples/v4lsrc/src/lib.rs
index 5397115c6..4e0b96574 100644
--- a/examples/v4lsrc/src/lib.rs
+++ b/examples/v4lsrc/src/lib.rs
@@ -94,9 +94,9 @@ impl CuTaskLifecycle for Video4LinuxSource {
 }
 
 impl CuSrcTask for Video4LinuxSource {
-    type Payload = ImageMsg;
+    type Output = ImageMsg;
 
-    fn process(&mut self, empty_msg: &mut CuMsg<Self::Payload>) -> CuResult<()> {
+    fn process(&mut self, empty_msg: &mut CuMsg<Self::Output>) -> CuResult<()> {
         let stream = self.stream.as_ref().unwrap();
         if let Ok(buffer) = stream.next() {
             let buffer = buffer.lock();