From 292227c83753564cde90de7a4f43d9ef4660bd4c Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Tue, 25 Nov 2025 15:10:53 +0800
Subject: Improve documentation for system action and config file crates

---
 crates/utils/cfg_file/cfg_file_derive/src/lib.rs | 29 +++++++++-
 crates/utils/cfg_file/src/config.rs              | 70 +++++++++++++++++++++++-
 2 files changed, 97 insertions(+), 2 deletions(-)

(limited to 'crates/utils/cfg_file')

diff --git a/crates/utils/cfg_file/cfg_file_derive/src/lib.rs b/crates/utils/cfg_file/cfg_file_derive/src/lib.rs
index e50a929..e916311 100644
--- a/crates/utils/cfg_file/cfg_file_derive/src/lib.rs
+++ b/crates/utils/cfg_file/cfg_file_derive/src/lib.rs
@@ -4,7 +4,34 @@ use proc_macro::TokenStream;
 use quote::quote;
 use syn::parse::ParseStream;
 use syn::{Attribute, DeriveInput, Expr, parse_macro_input};
-
+/// # Macro - ConfigFile
+///
+/// ## Usage
+///
+/// Use `#[derive(ConfigFile)]` to derive the ConfigFile trait for a struct
+///
+/// Specify the default storage path via `#[cfg_file(path = "...")]`
+///
+/// ## About the `cfg_file` attribute macro
+///
+/// Use `#[cfg_file(path = "string")]` to specify the configuration file path
+///
+/// Or use `#[cfg_file(path = constant_expression)]` to specify the configuration file path
+///
+/// ## Path Rules
+///
+/// Paths starting with `"./"`: relative to the current working directory
+///
+/// Other paths: treated as absolute paths
+///
+/// When no path is specified: use the struct name + ".json" as the default filename (e.g., `my_struct.json`)
+///
+/// ## Example
+/// ```ignore
+/// #[derive(ConfigFile)]
+/// #[cfg_file(path = "./config.json")]
+/// struct AppConfig;
+/// ```
 #[proc_macro_derive(ConfigFile, attributes(cfg_file))]
 pub fn derive_config_file(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
diff --git a/crates/utils/cfg_file/src/config.rs b/crates/utils/cfg_file/src/config.rs
index a1eb301..a38da9a 100644
--- a/crates/utils/cfg_file/src/config.rs
+++ b/crates/utils/cfg_file/src/config.rs
@@ -33,12 +33,50 @@ impl ConfigFormat {
     }
 }
 
+/// # Trait - ConfigFile
+///
+/// Used to implement more convenient persistent storage functionality for structs
+///
+/// This trait requires the struct to implement Default and serde's Serialize and Deserialize traits
+///
+/// ## Implementation
+///
+/// ```ignore
+/// // Your struct
+/// #[derive(Default, Serialize, Deserialize)]
+/// struct YourData;
+///
+/// impl ConfigFile for YourData {
+///     type DataType = YourData;
+///
+///     // Specify default path
+///     fn default_path() -> Result<PathBuf, Error> {
+///         Ok(current_dir()?.join("data.json"))
+///     }
+/// }
+/// ```
+///
+/// > **Using derive macro**
+/// >
+/// > We provide the derive macro `#[derive(ConfigFile)]`
+/// >
+/// > You can implement this trait more quickly, please check the module cfg_file::cfg_file_derive
+///
 #[async_trait]
 pub trait ConfigFile: Serialize + for<'a> Deserialize<'a> + Default {
     type DataType: Serialize + for<'a> Deserialize<'a> + Default + Send + Sync;
 
     fn default_path() -> Result<PathBuf, Error>;
 
+    /// # Read from default path
+    ///
+    /// Read data from the path specified by default_path()
+    ///
+    /// ```ignore
+    /// fn main() -> Result<(), std::io::Error> {
+    ///     let data = YourData::read().await?;
+    /// }
+    /// ```
     async fn read() -> Result<Self::DataType, std::io::Error>
     where
         Self: Sized + Send + Sync,
@@ -47,6 +85,16 @@ pub trait ConfigFile: Serialize + for<'a> Deserialize<'a> + Default {
         Self::read_from(path).await
     }
 
+    /// # Read from the given path
+    ///
+    /// Read data from the path specified by the path parameter
+    ///
+    /// ```ignore
+    /// fn main() -> Result<(), std::io::Error> {
+    ///     let data_path = current_dir()?.join("data.json");
+    ///     let data = YourData::read_from(data_path).await?;
+    /// }
+    /// ```
     async fn read_from(path: impl AsRef<Path> + Send) -> Result<Self::DataType, std::io::Error>
     where
         Self: Sized + Send + Sync,
@@ -91,6 +139,16 @@ pub trait ConfigFile: Serialize + for<'a> Deserialize<'a> + Default {
         Ok(result)
     }
 
+    /// # Write to default path
+    ///
+    /// Write data to the path specified by default_path()
+    ///
+    /// ```ignore
+    /// fn main() -> Result<(), std::io::Error> {
+    ///     let data = YourData::default();
+    ///     YourData::write(&data).await?;
+    /// }
+    /// ```
     async fn write(val: &Self::DataType) -> Result<(), std::io::Error>
     where
         Self: Sized + Send + Sync,
@@ -98,7 +156,17 @@ pub trait ConfigFile: Serialize + for<'a> Deserialize<'a> + Default {
         let path = Self::default_path()?;
         Self::write_to(val, path).await
     }
-
+    /// # Write to the given path
+    ///
+    /// Write data to the path specified by the path parameter
+    ///
+    /// ```ignore
+    /// fn main() -> Result<(), std::io::Error> {
+    ///     let data = YourData::default();
+    ///     let data_path = current_dir()?.join("data.json");
+    ///     YourData::write_to(&data, data_path).await?;
+    /// }
+    /// ```
     async fn write_to(
         val: &Self::DataType,
         path: impl AsRef<Path> + Send,
-- 
cgit