docs: enable running doctests in comp and pathf build modules

2 files changed, 89 insertions, 16 deletions

diff --git a/mingling_core/src/build/comp.rs b/mingling_core/src/build/comp.rs
index be53463..d6bb34f 100644
--- a/mingling_core/src/build/comp.rs
+++ b/mingling_core/src/build/comp.rs
@@ -1,4 +1,3 @@
-// Doc Not Optimize
 use std::path::PathBuf;
 
 use just_template::tmpl;
@@ -17,15 +16,18 @@ const TMPL_COMP_PWSH: &str = include_str!("../../tmpls/comps/pwsh.ps1");
 /// Scripts are written to the `OUT_DIR` (or `target/` if `OUT_DIR` is not set).
 ///
 /// # Example
-/// ```rust,ignore
-/// # use mingling_core::comp::ShellFlag;
+/// ```
+/// # #[cfg(all(feature = "build", feature = "comp"))] {
+/// # temp_env::with_var("OUT_DIR", Some(".temp/target/test/out/"), || {
+/// # use mingling_core::ShellFlag;
 /// # use mingling_core::build::build_comp_scripts;
-///
 /// // Generate completion scripts for "myapp"
 /// build_comp_scripts("myapp").unwrap();
 ///
 /// // Generate completion scripts for current package
 /// build_comp_scripts(env!("CARGO_PKG_NAME")).unwrap();
+/// # });
+/// # }
 /// ```
 pub fn build_comp_scripts(name: &str) -> Result<(), std::io::Error> {
     #[cfg(target_os = "windows")]
@@ -58,10 +60,14 @@ pub fn build_comp_scripts(name: &str) -> Result<(), std::io::Error> {
 /// resulting completion script to the target directory (typically `target/`).
 ///
 /// # Example
-/// ```rust,ignore
-/// # use mingling_core::comp::ShellFlag;
+/// ```
+/// # #[cfg(all(feature = "build", feature = "comp"))] {
+/// # temp_env::with_var("OUT_DIR", Some(".temp/target/test/out/"), || {
+/// # use mingling_core::ShellFlag;
 /// # use mingling_core::build::build_comp_script;
 /// build_comp_script(&ShellFlag::Bash, "myapp").unwrap();
+/// # });
+/// # }
 /// ```
 pub fn build_comp_script(shell_flag: &ShellFlag, bin_name: &str) -> Result<(), std::io::Error> {
     let out_dir = std::path::PathBuf::from(std::env::var("OUT_DIR").unwrap());
@@ -76,10 +82,14 @@ pub fn build_comp_script(shell_flag: &ShellFlag, bin_name: &str) -> Result<(), s
 /// and writes the resulting completion script to the specified directory.
 ///
 /// # Example
-/// ```rust,ignore
-/// # use mingling_core::comp::ShellFlag;
+/// ```
+/// # #[cfg(all(feature = "build", feature = "comp"))] {
+/// # temp_env::with_var("OUT_DIR", Some(".temp/target/test/out/"), || {
+/// # use mingling_core::ShellFlag;
 /// # use mingling_core::build::build_comp_script_to;
-/// build_comp_script_to(&ShellFlag::Bash, "myapp", "target/completions").unwrap();
+/// build_comp_script_to(&ShellFlag::Bash, "myapp", ".temp/target/test/out/").unwrap();
+/// # });
+/// # }
 /// ```
 pub fn build_comp_script_to(
     shell_flag: &ShellFlag,
@@ -102,10 +112,14 @@ pub fn build_comp_script_to(
 /// and writes the resulting completion script directly to the specified file path.
 ///
 /// # Example
-/// ```rust,ignore
-/// # use mingling_core::comp::ShellFlag;
+/// ```
+/// # #[cfg(all(feature = "build", feature = "comp"))] {
+/// # temp_env::with_var("OUT_DIR", Some(".temp/target/test/out/"), || {
+/// # use mingling_core::ShellFlag;
 /// # use mingling_core::build::build_comp_script_to_file;
-/// build_comp_script_to_file(&ShellFlag::Bash, "myapp", "target/completions/myapp_comp.sh").unwrap();
+/// build_comp_script_to_file(&ShellFlag::Bash, "myapp", ".temp/target/test/out/myapp.comp.sh").unwrap();
+/// # });
+/// # }
 /// ```
 pub fn build_comp_script_to_file(
     shell_flag: &ShellFlag,
diff --git a/mingling_core/src/build/pathf.rs b/mingling_core/src/build/pathf.rs
index 97cf672..23d3910 100644
--- a/mingling_core/src/build/pathf.rs
+++ b/mingling_core/src/build/pathf.rs
@@ -1,4 +1,3 @@
-// Doc Not Optimize
 #![allow(unused_imports)]
 
 pub use mingling_pathf::config::*;
@@ -8,8 +7,32 @@ pub use mingling_pathf::patterns::*;
 
 use std::path::Path;
 
-/// Wraps `analyze_and_build_type_mapping_for` with config derived from
-/// the crate's feature flags (e.g., `dispatch_tree`).
+/// Analyzes and builds a type mapping for a specific crate.
+///
+/// Accepts `crate_dir` and `output_dir`, and invokes `pathf` to build the type mapping.
+///
+/// # Arguments
+///
+/// - `crate_dir`: Root directory of the crate's source code to analyze (usually `CARGO_MANIFEST_DIR`).
+/// - `output_dir`: Output directory for generated artifacts (type mapping data).
+///
+/// # Returns
+///
+/// - On success: returns `Ok(())`;
+/// - On failure: returns the corresponding `MinglingPathfinderError`.
+///
+/// # Example
+///
+/// ```
+/// # #[cfg(all(feature = "build", feature = "pathf"))] {
+/// use mingling_core::build::analyze_and_build_type_mapping_for;
+/// use std::path::Path;
+///
+/// let crate_dir = Path::new(".");
+/// let output_dir = Path::new(".temp/target/out");
+/// analyze_and_build_type_mapping_for(crate_dir, output_dir).expect("analysis failed");
+/// # }
+/// ```
 pub fn analyze_and_build_type_mapping_for(
     crate_dir: &Path,
     output_dir: &Path,
@@ -20,7 +43,43 @@ pub fn analyze_and_build_type_mapping_for(
     mingling_pathf::analyze_and_build_type_mapping_for(crate_dir, output_dir, &config)
 }
 
-/// Wraps `analyze_and_build_type_mapping` (build.rs convenience) with config.
+/// # Analyzes and builds a type mapping
+///
+/// This function reads the current crate directory (`CARGO_PKG_NAME`) and output directory (`OUT_DIR`)
+/// from environment variables, automatically combines them into the target output path, and invokes
+/// the underlying analysis logic. Suitable for use in `build.rs`.
+///
+/// It also sends the `cargo:rerun-if-changed=src/` directive to Cargo so that a rebuild is
+/// automatically triggered when source code changes.
+///
+/// # Prerequisites
+///
+/// This function depends on the following environment variables, which are typically set
+/// automatically during a Cargo build:
+///
+/// - `CARGO_PKG_NAME`: Name of the current crate.
+/// - `OUT_DIR`: Build output directory provided by Cargo.
+///
+/// If these variables are missing, a corresponding [`MinglingPathfinderError`](crate::error::MinglingPathfinderError)
+/// is returned.
+///
+/// # Returns
+///
+/// Returns `Ok(())` on success; returns a corresponding
+/// [`MinglingPathfinderError`](crate::error::MinglingPathfinderError) on failure.
+///
+/// # Example
+///
+/// ```
+/// # #[cfg(all(feature = "build", feature = "pathf"))] {
+/// use mingling_core::build::analyze_and_build_type_mapping;
+///
+/// fn main() {
+///     analyze_and_build_type_mapping().expect("failed to build type mapping");
+/// }
+/// # }
+/// ```
+
 pub fn analyze_and_build_type_mapping() -> Result<(), crate::error::MinglingPathfinderError> {
     let config = mingling_pathf::config::PathfinderConfig {
         use_dispatch_tree: cfg!(feature = "dispatch_tree"),