补齐源码注释和 doctest

Author: developerworks

src/cli.rs

@@ -84,6 +84,45 @@ pub enum ConfigCommand {
 /// # Returns
 ///
 /// Returns `Ok(())` after the selected subcommand completes.
+///
+/// # Examples
+///
+/// ```no_run
+/// use clap::{Parser, Subcommand};
+/// use confique::Config;
+/// use rust_config_tree::{ConfigCommand, ConfigSchema, handle_config_command};
+/// use schemars::JsonSchema;
+///
+/// #[derive(Parser)]
+/// struct Cli {
+///     #[command(subcommand)]
+///     command: Command,
+/// }
+///
+/// #[derive(Subcommand)]
+/// enum Command {
+///     #[command(flatten)]
+///     Config(ConfigCommand),
+/// }
+///
+/// #[derive(Config, JsonSchema)]
+/// struct AppConfig {
+///     #[config(default = [])]
+///     include: Vec<std::path::PathBuf>,
+/// }
+///
+/// impl ConfigSchema for AppConfig {
+///     fn include_paths(layer: &<Self as Config>::Layer) -> Vec<std::path::PathBuf> {
+///         layer.include.clone().unwrap_or_default()
+///     }
+/// }
+///
+/// handle_config_command::<Cli, AppConfig>(
+///     ConfigCommand::ConfigValidate,
+///     std::path::Path::new("config.yaml"),
+/// )?;
+/// # Ok::<(), rust_config_tree::ConfigError>(())
+/// ```
 pub fn handle_config_command<C, S>(command: ConfigCommand, config_path: &Path) -> ConfigResult<()>
 where
     C: CommandFactory,
@@ -127,6 +166,20 @@ where
 /// # Returns
 ///
 /// This function writes to stdout and returns no value.
+///
+/// # Examples
+///
+/// ```no_run
+/// use clap::Parser;
+/// use clap_complete::aot::Shell;
+/// use rust_config_tree::print_shell_completion;
+///
+/// #[derive(Parser)]
+/// #[command(name = "myapp")]
+/// struct Cli {}
+///
+/// print_shell_completion::<Cli>(Shell::Bash);
+/// ```
 pub fn print_shell_completion<C>(shell: Shell)
 where
     C: CommandFactory,
@@ -150,6 +203,21 @@ where
 ///
 /// Returns `Ok(())` after the completion file is generated and any required
 /// startup file has been updated.
+///
+/// # Examples
+///
+/// ```no_run
+/// use clap::Parser;
+/// use clap_complete::aot::Shell;
+/// use rust_config_tree::install_shell_completion;
+///
+/// #[derive(Parser)]
+/// #[command(name = "myapp")]
+/// struct Cli {}
+///
+/// install_shell_completion::<Cli>(Shell::Zsh)?;
+/// # Ok::<(), rust_config_tree::ConfigError>(())
+/// ```
 pub fn install_shell_completion<C>(shell: Shell) -> ConfigResult<()>
 where
     C: CommandFactory,
@@ -185,9 +253,19 @@ where
 
 /// Resolves the current user's home directory from environment variables.
 ///
+/// # Arguments
+///
+/// This function has no arguments.
+///
 /// # Returns
 ///
 /// Returns the home directory when `HOME` or `USERPROFILE` is set.
+///
+/// # Examples
+///
+/// ```no_run
+/// // Internal helper; use `install_shell_completion` to resolve install paths.
+/// ```
 fn home_dir() -> Option<PathBuf> {
     std::env::var_os("HOME")
         .map(PathBuf::from)
@@ -218,6 +296,12 @@ impl ShellInstallTarget {
     /// # Returns
     ///
     /// Returns the shell-specific install target.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// // Internal helper; use `install_shell_completion` to construct targets.
+    /// ```
     fn new(shell: Shell, home_dir: &Path) -> ConfigResult<Self> {
         let target = match shell {
             Shell::Bash => Self {
@@ -276,6 +360,12 @@ impl ShellInstallTarget {
     ///
     /// Returns the startup-file block body, or `None` when the shell does not
     /// need startup-file changes.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// // Internal helper; use `install_shell_completion` to generate rc blocks.
+    /// ```
     fn rc_block_body(&self, generated_path: &Path, completion_dir: &Path) -> Option<String> {
         let generated_path = generated_path.to_str()?;
         let completion_dir = completion_dir.to_str()?;
@@ -320,6 +410,23 @@ impl ShellInstallTarget {
 /// # Returns
 ///
 /// Returns `Ok(())` after the startup file has been written.
+///
+/// # Examples
+///
+/// ```
+/// use std::fs;
+/// use clap_complete::aot::Shell;
+/// use rust_config_tree::upsert_managed_block;
+///
+/// let path = std::env::temp_dir().join("rust-config-tree-upsert-doctest.rc");
+/// upsert_managed_block("myapp", Shell::Bash, &path, "body\n")?;
+///
+/// let content = fs::read_to_string(&path)?;
+/// assert!(content.contains("# >>> myapp bash completions >>>"));
+/// assert!(content.contains("body"));
+/// # let _ = fs::remove_file(path);
+/// # Ok::<(), std::io::Error>(())
+/// ```
 pub fn upsert_managed_block(
     bin_name: &str,
     shell: Shell,

src/config.rs

@@ -50,6 +50,25 @@ pub trait ConfigSchema: Config + Sized {
     /// # Returns
     ///
     /// Returns include paths declared by `layer`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use confique::Config;
+    /// use rust_config_tree::ConfigSchema;
+    ///
+    /// #[derive(Config)]
+    /// struct AppConfig {
+    ///     #[config(default = [])]
+    ///     include: Vec<std::path::PathBuf>,
+    /// }
+    ///
+    /// impl ConfigSchema for AppConfig {
+    ///     fn include_paths(layer: &<Self as Config>::Layer) -> Vec<std::path::PathBuf> {
+    ///         layer.include.clone().unwrap_or_default()
+    ///     }
+    /// }
+    /// ```
     fn include_paths(layer: &<Self as Config>::Layer) -> Vec<PathBuf>;
 
     /// Overrides the generated template file path for a split nested section.
@@ -70,6 +89,32 @@ pub trait ConfigSchema: Config + Sized {
     ///
     /// Returns `Some(path)` to override the generated file path, or `None` to
     /// use the default section path.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use confique::Config;
+    /// use rust_config_tree::ConfigSchema;
+    ///
+    /// #[derive(Config)]
+    /// struct AppConfig {
+    ///     #[config(default = [])]
+    ///     include: Vec<std::path::PathBuf>,
+    /// }
+    ///
+    /// impl ConfigSchema for AppConfig {
+    ///     fn include_paths(layer: &<Self as Config>::Layer) -> Vec<std::path::PathBuf> {
+    ///         layer.include.clone().unwrap_or_default()
+    ///     }
+    ///
+    ///     fn template_path_for_section(section_path: &[&str]) -> Option<std::path::PathBuf> {
+    ///         match section_path {
+    ///             ["server"] => Some(std::path::PathBuf::from("config/server.yaml")),
+    ///             _ => None,
+    ///         }
+    ///     }
+    /// }
+    /// ```
     fn template_path_for_section(section_path: &[&str]) -> Option<PathBuf> {
         let _ = section_path;
         None

src/config_env.rs

@@ -38,9 +38,29 @@ impl ConfiqueEnvProvider {
     ///
     /// - `S`: Config schema whose metadata declares environment variable names.
     ///
+    /// # Arguments
+    ///
+    /// This function has no arguments.
+    ///
     /// # Returns
     ///
     /// Returns a provider that emits only environment variables declared by `S`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use confique::Config;
+    /// use rust_config_tree::ConfiqueEnvProvider;
+    ///
+    /// #[derive(Config)]
+    /// struct AppConfig {
+    ///     #[config(env = "APP_MODE", default = "demo")]
+    ///     mode: String,
+    /// }
+    ///
+    /// let provider = ConfiqueEnvProvider::new::<AppConfig>();
+    /// # let _ = provider;
+    /// ```
     pub fn new<S>() -> Self
     where
         S: Config,
@@ -69,6 +89,22 @@ impl ConfiqueEnvProvider {
 
 /// Supplies Figment data and source labels for schema-declared environment variables.
 impl Provider for ConfiqueEnvProvider {
+    /// Builds metadata used by Figment source tracing.
+    ///
+    /// # Arguments
+    ///
+    /// - `self`: Environment provider whose path-to-variable mapping should be
+    ///   exposed in metadata.
+    ///
+    /// # Returns
+    ///
+    /// Returns Figment metadata that renders schema paths as native env names.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// let _ = ();
+    /// ```
     fn metadata(&self) -> Metadata {
         let path_to_env = Arc::clone(&self.path_to_env);
 
@@ -79,12 +115,44 @@ impl Provider for ConfiqueEnvProvider {
         })
     }
 
+    /// Reads configured environment variables into Figment data.
+    ///
+    /// # Arguments
+    ///
+    /// - `self`: Environment provider wrapping the filtered Figment env source.
+    ///
+    /// # Returns
+    ///
+    /// Returns Figment data grouped by profile, or a Figment error.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// let _ = ();
+    /// ```
     fn data(&self) -> Result<Map<Profile, Dict>, figment::Error> {
         self.env.data()
     }
 }
 
 /// Recursively maps schema field paths to their declared environment variables.
+///
+/// # Arguments
+///
+/// - `meta`: `confique` metadata node to inspect.
+/// - `prefix`: Dot-separated field path prefix for `meta`.
+/// - `env_to_path`: Output map from uppercase environment names to field paths.
+/// - `path_to_env`: Output map from field paths to declared environment names.
+///
+/// # Returns
+///
+/// Returns no value; both output maps are updated in place.
+///
+/// # Examples
+///
+/// ```no_run
+/// let _ = ();
+/// ```
 fn collect_env_mapping(
     meta: &'static Meta,
     prefix: &str,

src/config_format.rs

@@ -32,6 +32,16 @@ impl ConfigFormat {
     /// # Returns
     ///
     /// Returns the inferred [`ConfigFormat`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use rust_config_tree::ConfigFormat;
+    ///
+    /// assert_eq!(ConfigFormat::from_path("config.toml"), ConfigFormat::Toml);
+    /// assert_eq!(ConfigFormat::from_path("config.json5"), ConfigFormat::Json);
+    /// assert_eq!(ConfigFormat::from_path("config.unknown"), ConfigFormat::Yaml);
+    /// ```
     pub fn from_path(path: impl AsRef<Path>) -> Self {
         match path.as_ref().extension().and_then(OsStr::to_str) {
             Some("toml") => Self::Toml,
@@ -42,6 +52,20 @@ impl ConfigFormat {
 }
 
 /// Builds the YAML renderer options used by default templates.
+///
+/// # Arguments
+///
+/// This function has no arguments.
+///
+/// # Returns
+///
+/// Returns YAML format options shared by generated templates.
+///
+/// # Examples
+///
+/// ```no_run
+/// let _ = ();
+/// ```
 pub(crate) fn yaml_options() -> confique::yaml::FormatOptions {
     let mut options = confique::yaml::FormatOptions::default();
     options.indent = 2;
@@ -52,6 +76,20 @@ pub(crate) fn yaml_options() -> confique::yaml::FormatOptions {
 }
 
 /// Builds the TOML renderer options used by default templates.
+///
+/// # Arguments
+///
+/// This function has no arguments.
+///
+/// # Returns
+///
+/// Returns TOML format options shared by generated templates.
+///
+/// # Examples
+///
+/// ```no_run
+/// let _ = ();
+/// ```
 pub(crate) fn toml_options() -> confique::toml::FormatOptions {
     let mut options = confique::toml::FormatOptions::default();
     options.general.comments = true;
@@ -61,6 +99,20 @@ pub(crate) fn toml_options() -> confique::toml::FormatOptions {
 }
 
 /// Builds the JSON5 renderer options used by default templates.
+///
+/// # Arguments
+///
+/// This function has no arguments.
+///
+/// # Returns
+///
+/// Returns JSON5 format options shared by generated templates.
+///
+/// # Examples
+///
+/// ```no_run
+/// let _ = ();
+/// ```
 pub(crate) fn json5_options() -> confique::json5::FormatOptions {
     let mut options = confique::json5::FormatOptions::default();
     options.indent = 2;