Improve documentation for system action and config file crates

3 files changed, 123 insertions, 6 deletions

diff --git a/crates/system_action/action_macros/src/lib.rs b/crates/system_action/action_macros/src/lib.rs
index 4c03b63..e6616b4 100644
--- a/crates/system_action/action_macros/src/lib.rs
+++ b/crates/system_action/action_macros/src/lib.rs
@@ -2,13 +2,56 @@ use proc_macro::TokenStream;
 use quote::quote;
 use syn::{ItemFn, parse_macro_input};
 
-/// A procedural macro for generating structs that implement the Action trait
+/// # Macro - Generate Action
 ///
-/// Usage:
-/// #[action_gen] or #[action_gen(local)]
-/// pub fn my_action(ctx: ActionContext, arg: MyArg) -> Result<MyReturn, TcpTargetError> {
-///     todo!()
+/// When annotating a function with the `#[action_gen]` macro in the following format, it generates boilerplate code for client-server interaction
+///
+/// ```ignore
+/// #[action_gen]
+/// async fn action_name(ctx: ActionContext, argument: YourArgument) -> Result<YourResult, TcpTargetError> {
+///     // Write your client and server logic here
+///     if ctx.is_proc_on_remote() {
+///         // Server logic
+///     }
+///     if ctx.is_proc_on_local() {
+///         // Client logic
+///     }
+/// }
+/// ```
+///
+/// > WARNING:
+/// > For Argument and Result types, the `action_gen` macro only supports types that derive serde's Serialize and Deserialize
+///
+/// ## Generated Code
+///
+/// `action_gen` will generate the following:
+///
+/// 1. Complete implementation of Action<Args, Return>
+/// 2. Process / Register method
+///
+/// ## How to use
+///
+/// You can use your generated method as follows
+///
+/// ```ignore
+/// async fn main() -> Result<(), TcpTargetError> {
+///
+///     // Prepare your argument
+///     let args = YourArgument::default();
+///
+///     // Create a pool and context
+///     let mut pool = ActionPool::new();
+///     let ctx = ActionContext::local();
+///
+///     // Register your action
+///     register_your_action(&mut pool);
+///
+///     // Process your action
+///     proc_your_action(&pool, ctx, args).await?;
+///
+///     Ok(())
 /// }
+/// ```
 #[proc_macro_attribute]
 pub fn action_gen(attr: TokenStream, item: TokenStream) -> TokenStream {
     let input_fn = parse_macro_input!(item as ItemFn);
diff --git a/crates/system_action/src/action.rs b/crates/system_action/src/action.rs
index ef1bf11..62425ff 100644
--- a/crates/system_action/src/action.rs
+++ b/crates/system_action/src/action.rs
@@ -5,6 +5,40 @@ use std::sync::Arc;
 use tcp_connection::{error::TcpTargetError, instance::ConnectionInstance};
 use tokio::{net::TcpStream, sync::Mutex};
 
+/// # Trait - Action<Args, Return>
+///
+/// A trait used to describe the interaction pattern between client and server
+///
+/// ## Generics
+///
+/// Args: Represents the parameter type required for this action
+///
+/// Return: Represents the return type of this action
+///
+/// The above generics must implement serde's Serialize and DeserializeOwned traits,
+/// and must be sendable between threads
+///
+/// ## Implementation
+///
+/// ```ignore
+/// pub trait Action<Args, Return>
+/// where
+///     Args: Serialize + DeserializeOwned + Send,
+///     Return: Serialize + DeserializeOwned + Send,
+/// {
+///     /// Name, used to inform the server which action to execute
+///     fn action_name() -> &'static str;
+///
+///     /// Whether it's a local Action, used to inform the system if it only runs locally
+///     fn is_remote_action() -> bool;
+///
+///     /// Action processing logic
+///     fn process(
+///         context: ActionContext,
+///         args: Args,
+///     ) -> impl std::future::Future<Output = Result<Return, TcpTargetError>> + Send;
+/// }
+/// ```
 pub trait Action<Args, Return>
 where
     Args: Serialize + DeserializeOwned + Send,
@@ -20,6 +54,28 @@ where
     ) -> impl std::future::Future<Output = Result<Return, TcpTargetError>> + Send;
 }
 
+/// # Struct - ActionContext
+///
+/// Used to inform the Action about the current execution environment
+///
+/// ## Creation
+///
+/// Create ActionContext using the following methods:
+///
+/// ```ignore
+///
+/// // The instance here is the connection instance passed from external sources for communicating with the server
+/// // For specific usage, please refer to the `/crates/utils/tcp_connection` section
+///
+/// fn init_local_action_ctx(instance: ConnectionInstance) {
+///     // Create context and specify execution on local
+///     let mut ctx = ActionContext::local();
+/// }
+///
+/// fn init_remote_action_ctx(instance: ConnectionInstance) {
+///     // Create context and specify execution on remote
+///     let mut ctx = ActionContext::remote();
+/// }
 #[derive(Default)]
 pub struct ActionContext {
     /// Whether the action is executed locally or remotely
diff --git a/crates/system_action/src/action_pool.rs b/crates/system_action/src/action_pool.rs
index c3ad4a1..019fa6d 100644
--- a/crates/system_action/src/action_pool.rs
+++ b/crates/system_action/src/action_pool.rs
@@ -15,7 +15,25 @@ type ProcEndCallback = fn() -> ProcEndFuture;
 type ProcBeginFuture<'a> = Pin<Box<dyn Future<Output = Result<(), TcpTargetError>> + Send + 'a>>;
 type ProcEndFuture = Pin<Box<dyn Future<Output = Result<(), TcpTargetError>> + Send>>;
 
-/// A pool of registered actions that can be processed by name
+/// # Struct - ActionPool
+///
+/// This struct is used to register and record all accessible and executable actions
+///
+/// It also registers `on_proc_begin` and `on_proc_end` callback functions
+/// used for action initialization
+///
+/// ## Creating and registering actions
+/// ```ignore
+/// fn init_action_pool() {
+///     let mut pool = Action::new();
+///
+///     // Register action
+///     pool.register<YourAction, ActionArgument, ActionReturn>();
+///
+///     // If the action is implemented with `#[action_gen]`, you can also do
+///     register_your_action(&mut pool);
+/// }
+/// ```
 pub struct ActionPool {
     /// HashMap storing action name to action implementation mapping
     actions: std::collections::HashMap<&'static str, Box<dyn ActionErased>>,