feat: propagate doc comments on flags and arguments to --help/-h + structs derive refactor

.github/workflows/tests.yml

@@ -20,3 +20,23 @@ jobs:
         profile: minimal
     - name: Tests
       run: cargo test --workspace
+  # there're sometimes warnings, which signal, that the generated doc
+  # won't look as expected, when rendered, and sometimes errors, which will prevent doc from being
+  # generated at release time altogether.
+  cargo-doc:
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Toolchain
+      uses: actions-rs/toolchain@v1
+      with:
+        profile: minimal
+        toolchain: stable
+        default: true
+    - name: run cargo doc
+      env:
+        RUSTDOCFLAGS: -D warnings
+      run: |
+        cargo doc -p interactive-clap
+        cargo doc -p interactive-clap-derive --document-private-items

examples/struct_with_subargs.rs

@@ -11,9 +11,14 @@ use interactive_clap::{ResultFromCli, ToCliArgs};
 #[derive(Debug, Clone, interactive_clap::InteractiveClap)]
 struct Account {
     /// Change SocialDb prefix
+    ///
+    /// It's a paraghraph, describing, this argument usage in more detail
+    /// than just the headline
     #[interactive_clap(long)]
     #[interactive_clap(skip_interactive_input)]
+    #[interactive_clap(verbatim_doc_comment)]
     social_db_folder: Option<String>,
+    /// Sender account
     #[interactive_clap(subargs)]
     account: Sender,
 }

interactive-clap-derive/Cargo.toml

@@ -22,3 +22,11 @@ syn = "1"
 prettyplease = "0.1"
 insta = "1"
 syn = { version = "1", features = ["full"] }
+
+[package.metadata.docs.rs]
+# Additional `RUSTDOCFLAGS` to set (default: [])
+rustdoc-args = ["--document-private-items"]
+
+[features]
+default = []
+introspect = []

interactive-clap-derive/docs/clap_enum_for_named_arg_docstring.md

@@ -0,0 +1,27 @@
+derive of helper enum for structs with `#[interactive_clap(named_arg)]` on fields
+
+
+```rust,ignore
+struct #name {
+    #[interactive_clap(named_arg)]
+    ///Specify a sender
+    field_name: Sender,
+}
+```
+
+gets transformed
+=> 
+
+```rust,ignore
+#[derive(Debug, Clone, clap::Parser, interactive_clap_derive::ToCliArgs)]
+pub enum ClapNamedArgSenderFor#name {
+    ///Specify a sender
+    FieldName(<Sender as interactive_clap::ToCli>::CliVariant),
+}
+impl From<Sender> for ClapNamedArgSenderFor#name {
+    fn from(item: Sender) -> Self {
+        Self::FieldName(<Sender as interactive_clap::ToCli>::CliVariant::from(item))
+    }
+}
+```
+

interactive-clap-derive/docs/structs_from_cli_trait_docstring.md

@@ -0,0 +1,70 @@
+`interactive_clap::FromCli` derive
+
+This modules describes derive of `interactive_clap::FromCli` trait for `#name` struct,
+which happens during derive of [`crate::InteractiveClap`] for `#name` struct:
+
+The implementation combines usages of all of [super::structs::to_cli_trait], [super::structs::input_args_impl],
+[super::structs::to_interactive_clap_context_scope_trait]
+
+
+derive input `#name`
+
+```rust,ignore
+struct #name {
+    age: u64,
+    first_name: String,
+}
+```
+
+gets transformed
+=> 
+
+```rust,ignore
+impl interactive_clap::FromCli for #name {
+    type FromCliContext = ();
+    type FromCliError = color_eyre::eyre::Error;
+    fn from_cli(
+        optional_clap_variant: Option<<Self as interactive_clap::ToCli>::CliVariant>,
+        context: Self::FromCliContext,
+    ) -> interactive_clap::ResultFromCli<
+        <Self as interactive_clap::ToCli>::CliVariant,
+        Self::FromCliError,
+    >
+    where
+        Self: Sized + interactive_clap::ToCli,
+    {
+        let mut clap_variant = optional_clap_variant.clone().unwrap_or_default();
+        if clap_variant.age.is_none() {
+            clap_variant
+                .age = match Self::input_age(&context) {
+                Ok(Some(age)) => Some(age),
+                Ok(None) => {
+                    return interactive_clap::ResultFromCli::Cancel(Some(clap_variant));
+                }
+                Err(err) => {
+                    return interactive_clap::ResultFromCli::Err(Some(clap_variant), err);
+                }
+            };
+        }
+        let age = clap_variant.age.clone().expect("Unexpected error");
+        if clap_variant.first_name.is_none() {
+            clap_variant
+                .first_name = match Self::input_first_name(&context) {
+                Ok(Some(first_name)) => Some(first_name),
+                Ok(None) => {
+                    return interactive_clap::ResultFromCli::Cancel(Some(clap_variant));
+                }
+                Err(err) => {
+                    return interactive_clap::ResultFromCli::Err(Some(clap_variant), err);
+                }
+            };
+        }
+        let first_name = clap_variant.first_name.clone().expect("Unexpected error");
+        let new_context_scope = InteractiveClapContextScopeFor#name {
+            age: age.into(),
+            first_name: first_name.into(),
+        };
+        interactive_clap::ResultFromCli::Ok(clap_variant)
+    }
+}
+```

interactive-clap-derive/docs/structs_input_args_impl_docstring.md

@@ -0,0 +1,44 @@
+per-field input with [inquire::CustomType](https://docs.rs/inquire/0.6.2/inquire/struct.CustomType.html) impl block
+
+This modules describes derive of input args implementation block for `#name` struct,
+which contains functions `input_#field_ident` per each field,
+which prompt for value of each field via [inquire::CustomType](https://docs.rs/inquire/0.6.2/inquire/struct.CustomType.html)
+, which happens during derive of [`crate::InteractiveClap`] for `#name` struct:
+
+derive input `#name`
+
+```rust,ignore
+struct #name {
+    age: u64,
+    first_name: String,
+}
+```
+
+
+gets transformed
+=> 
+
+```rust,ignore
+impl #name {
+    fn input_age(_context: &()) -> color_eyre::eyre::Result<Option<u64>> {
+        match inquire::CustomType::new("age").prompt() {
+            Ok(value) => Ok(Some(value)),
+            Err(
+                inquire::error::InquireError::OperationCanceled
+                | inquire::error::InquireError::OperationInterrupted,
+            ) => Ok(None),
+            Err(err) => Err(err.into()),
+        }
+    }
+    fn input_first_name(_context: &()) -> color_eyre::eyre::Result<Option<String>> {
+        match inquire::CustomType::new("first_name").prompt() {
+            Ok(value) => Ok(Some(value)),
+            Err(
+                inquire::error::InquireError::OperationCanceled
+                | inquire::error::InquireError::OperationInterrupted,
+            ) => Ok(None),
+            Err(err) => Err(err.into()),
+        }
+    }
+}
+```

interactive-clap-derive/docs/structs_to_cli_trait_docstring.md

@@ -0,0 +1,54 @@
+`interactive_clap::ToCli` derive
+
+This module describes the derive logic of `#cli_name` struct used as `CliVariant` in
+implementation of `interactive_clap::ToCli`, which happens during derive of [`crate::InteractiveClap`] for `#name` struct.
+
+```rust,ignore
+#[derive(Debug, Default, Clone, clap::Parser, interactive_clap::ToCliArgs)]
+#[clap(author, version, about, long_about = None)]
+pub struct #cli_name {
+   #( #cli_fields, )*
+}
+
+impl interactive_clap::ToCli for #name {
+   type CliVariant = #cli_name;
+}
+```
+
+Where `interactive_clap::ToCli` is:
+
+```rust,ignore
+pub trait ToCli {
+   type CliVariant;
+}
+```
+Additionally a [`clap::Parser`](https://docs.rs/clap/4.5.24/clap/trait.Parser.html) adapter
+for `#name` and `From<#name> for #cli_name` conversion are defined:
+
+```rust,ignore
+impl #name {
+   pub fn try_parse() -> Result<#cli_name, clap::Error> {
+       <#cli_name as clap::Parser>::try_parse()
+   }
+
+   pub fn parse() -> #cli_name {
+       <#cli_name as clap::Parser>::parse()
+   }
+
+   pub fn try_parse_from<I, T>(itr: I) -> Result<#cli_name, clap::Error>
+   where
+       I: ::std::iter::IntoIterator<Item = T>,
+       T: ::std::convert::Into<::std::ffi::OsString> + ::std::clone::Clone,
+   {
+       <#cli_name as clap::Parser>::try_parse_from(itr)
+   }
+}
+
+impl From<#name> for #cli_name {
+   fn from(args: #name) -> Self {
+       Self {
+           #( #fields_conversion, )*
+       }
+   }
+}
+```

interactive-clap-derive/docs/structs_to_interactive_clap_context_scope_trait_docstring.md

@@ -0,0 +1,26 @@
+`interactive_clap::ToInteractiveClapContextScope` derive
+
+This modules describes derive of `interactive_clap::ToInteractiveClapContextScope` trait for `#name` struct,
+which happens during derive of [`crate::InteractiveClap`] for `#name` struct:
+
+derive input `#name`
+
+```rust,ignore
+struct #name {
+    age: u64,
+    first_name: String,
+}
+```
+
+gets transformed
+=> 
+
+```rust,ignore
+impl #name pub struct InteractiveClapContextScopeFor#name {
+    pub age: u64,
+    pub first_name: String,
+}
+impl interactive_clap::ToInteractiveClapContextScope for #name {
+    type InteractiveClapContextScope = InteractiveClapContextScopeFor#name;
+}
+```

interactive-clap-derive/src/debug.rs

@@ -0,0 +1,22 @@
+#[cfg(feature = "introspect")]
+macro_rules! dbg_cond {
+    ($($val:expr),* ) => {
+        dbg!($($val),*)
+    };
+}
+
+/// this macro under `introspect` feature can be used to debug how derive proc macros
+/// ([`crate::InteractiveClap`], [`crate::ToCliArgs`]) work
+///
+/// ```bash
+/// # interactive-clap-derive folder
+/// cargo test test_doc_comments_propagate --features introspect -- --nocapture
+/// # from repo root
+/// cargo run --example struct_with_subargs --features interactive-clap-derive/introspect
+/// ```
+#[cfg(not(feature = "introspect"))]
+macro_rules! dbg_cond {
+    ($($val:expr),*) => {
+        // no-op
+    };
+}

interactive-clap-derive/src/derives/interactive_clap/methods/choose_variant.rs → interactive-clap-derive/src/derives/interactive_clap/common_methods/choose_variant.rs

@@ -9,6 +9,7 @@ pub fn fn_choose_variant(
     ast: &syn::DeriveInput,
     variants: &syn::punctuated::Punctuated<syn::Variant, syn::token::Comma>,
 ) -> proc_macro2::TokenStream {
+    dbg_cond!("entered `fn_choose_variant`");
     let name = &ast.ident;
     let interactive_clap_attrs_context =
         super::interactive_clap_attrs_context::InteractiveClapAttrsContext::new(ast);
@@ -19,7 +20,9 @@ pub fn fn_choose_variant(
     let mut ast_attrs: Vec<&str> = std::vec::Vec::new();
 
     if !ast.attrs.is_empty() {
-        for attr in ast.attrs.clone() {
+        #[allow(clippy::unused_enumerate_index)]
+        for (_index, attr) in ast.attrs.clone().into_iter().enumerate() {
+            dbg_cond!(_index, &attr);
             if attr.path.is_ident("interactive_clap") {
                 for attr_token in attr.tokens.clone() {
                     if let proc_macro2::TokenTree::Group(group) = attr_token {
@@ -29,16 +32,21 @@ pub fn fn_choose_variant(
                     }
                 }
             };
+            dbg_cond!(attr.path.is_ident("strum_discriminants"));
             if attr.path.is_ident("strum_discriminants") {
                 for attr_token in attr.tokens.clone() {
                     if let proc_macro2::TokenTree::Group(group) = attr_token {
-                        if &group.stream().to_string() == "derive(EnumMessage, EnumIter)" {
+                        let group_stream_no_whitespace =
+                            group.stream().to_string().replace(" ", "");
+                        dbg_cond!(&group_stream_no_whitespace);
+                        if &group_stream_no_whitespace == "derive(EnumMessage,EnumIter)" {
                             ast_attrs.push("strum_discriminants");
                         };
                     }
                 }
             };
         }
+        dbg_cond!(&ast_attrs);
         if ast_attrs.contains(&"strum_discriminants") {
             let doc_attrs = ast
                 .attrs

interactive-clap-derive/src/derives/interactive_clap/common_methods/mod.rs

@@ -0,0 +1,4 @@
+pub mod choose_variant;
+pub mod fields_with_skip_default_input_arg;
+pub mod from_cli_for_enum;
+pub mod interactive_clap_attrs_context;