From 9f5a0f2e9325264564bc6fe9ff544c034ad16287 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Mon, 20 Jul 2026 14:49:47 +0800
Subject: chore: add missing docs lint and document public API

Add `#![deny(missing_docs)]` across multiple crates and fill in
documentation for all public items, including struct fields, enum
variants, trait methods, and proc macros.  Also mark two shell scripts
as executable.
---
 mingling_pathf/src/error.rs                    | 16 ++++++++++++++--
 mingling_pathf/src/lib.rs                      |  1 +
 mingling_pathf/src/pattern_analyzer.rs         |  2 ++
 mingling_pathf/src/patterns/dispatcher.rs      |  8 ++++++++
 mingling_pathf/src/patterns/dispatcher_clap.rs |  6 ++++++
 5 files changed, 31 insertions(+), 2 deletions(-)

(limited to 'mingling_pathf/src')

diff --git a/mingling_pathf/src/error.rs b/mingling_pathf/src/error.rs
index 70a8f6e..d384901 100644
--- a/mingling_pathf/src/error.rs
+++ b/mingling_pathf/src/error.rs
@@ -22,7 +22,9 @@ pub enum MinglingPathfinderError {
     /// `parent` is the directory containing the file that declared the module.
     /// `module_name` is the name of the module that could not be found.
     ModuleNotFound {
+        /// The directory containing the file that declared the module.
         parent: PathBuf,
+        /// The name of the module that could not be found.
         module_name: String,
     },
 
@@ -30,7 +32,12 @@ pub enum MinglingPathfinderError {
     ///
     /// `file` is the file containing the invalid attribute.
     /// `path_attr` is the value of the `#[path]` attribute.
-    PathPointsOutside { file: PathBuf, path_attr: String },
+    PathPointsOutside {
+        /// The file containing the invalid `#[path]` attribute.
+        file: PathBuf,
+        /// The value of the `#[path]` attribute that points outside the project.
+        path_attr: String,
+    },
 
     /// No entry point file (`main.rs`, `lib.rs`, or any file under `bin/`) was found.
     NoEntryPointFound,
@@ -39,7 +46,12 @@ pub enum MinglingPathfinderError {
     ///
     /// `path` is the file that failed to parse.
     /// `message` contains details from the parser.
-    SynError { path: PathBuf, message: String },
+    SynError {
+        /// The file that failed to parse.
+        path: PathBuf,
+        /// Details from the parser about the parse failure.
+        message: String,
+    },
 }
 
 impl fmt::Display for MinglingPathfinderError {
diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs
index 557ae45..69ff3ac 100644
--- a/mingling_pathf/src/lib.rs
+++ b/mingling_pathf/src/lib.rs
@@ -1,5 +1,6 @@
 #![allow(clippy::needless_doctest_main)]
 #![doc = include_str!("../README.md")]
+#![deny(missing_docs)]
 
 pub mod config;
 pub mod error;
diff --git a/mingling_pathf/src/pattern_analyzer.rs b/mingling_pathf/src/pattern_analyzer.rs
index 5bbc3b4..31d6918 100644
--- a/mingling_pathf/src/pattern_analyzer.rs
+++ b/mingling_pathf/src/pattern_analyzer.rs
@@ -100,10 +100,12 @@ pub struct PatternAnalyzer {
 }
 
 impl PatternAnalyzer {
+    /// Creates a new empty `PatternAnalyzer`.
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Registers a new pattern for analysis.
     pub fn add_pattern(&mut self, pattern: impl AnalyzePattern + 'static) {
         self.patterns.push(Box::new(pattern));
     }
diff --git a/mingling_pathf/src/patterns/dispatcher.rs b/mingling_pathf/src/patterns/dispatcher.rs
index 6796a2c..eaa53f0 100644
--- a/mingling_pathf/src/patterns/dispatcher.rs
+++ b/mingling_pathf/src/patterns/dispatcher.rs
@@ -20,10 +20,18 @@ use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
 /// - `CMD*` — the dispatcher struct (always)
 /// - `__internal_dispatcher_*` — dispatch tree static (when `use_dispatch_tree` is true)
 pub struct DispatcherPattern {
+    /// Whether the dispatcher generates a dispatch tree static (`__internal_dispatcher_*`).
     pub use_dispatch_tree: bool,
 }
 
 impl DispatcherPattern {
+    /// Creates a new `DispatcherPattern`.
+    ///
+    /// # Arguments
+    ///
+    /// * `use_dispatch_tree` — when `true`, the generated dispatcher also produces a
+    ///   `__internal_dispatcher_*` static dispatch tree item. Set this based on whether
+    ///   your macro invocation includes the `use_dispatch_tree` configuration.
     pub fn new(use_dispatch_tree: bool) -> Self {
         Self { use_dispatch_tree }
     }
diff --git a/mingling_pathf/src/patterns/dispatcher_clap.rs b/mingling_pathf/src/patterns/dispatcher_clap.rs
index 1a86ad5..0a249b4 100644
--- a/mingling_pathf/src/patterns/dispatcher_clap.rs
+++ b/mingling_pathf/src/patterns/dispatcher_clap.rs
@@ -29,10 +29,16 @@ use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern};
 /// - `#[dispatcher_clap("greet", CMDGreet, help = true)] struct EntryGreet { ... }`
 /// - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet, help = true)] struct EntryGreet { ... }`
 pub struct DispatcherClapPattern {
+    /// Whether to include the `__internal_dispatcher_*` dispatch tree static in the analysis.
     pub use_dispatch_tree: bool,
 }
 
 impl DispatcherClapPattern {
+    /// Creates a new `DispatcherClapPattern` with the given configuration.
+    ///
+    /// # Parameters
+    /// - `use_dispatch_tree`: When `true`, enables analysis of the `__internal_dispatcher_*`
+    ///   static dispatch tree for each matched command.
     pub fn new(use_dispatch_tree: bool) -> Self {
         Self { use_dispatch_tree }
     }
-- 
cgit