integration: Polish MarkdownOptions type + add test for custom option…

…s behavior

docs/examples/complex-app-custom.md

@@ -0,0 +1,65 @@
+# Some Custom Title for Complex App
+
+This document contains the help content for the `complex-app` command-line program.
+
+**Command Overview:**
+
+* [`complex-app`↴](#complex-app)
+* [`complex-app test`↴](#complex-app-test)
+* [`complex-app only-hidden-options`↴](#complex-app-only-hidden-options)
+
+## `complex-app`
+
+An example command-line tool
+
+**Usage:** `complex-app [OPTIONS] [NAME] [COMMAND]`
+
+###### **Subcommands:**
+
+* `test` — does testing things
+* `only-hidden-options` — Demo that `Options` is not printed if all options are hidden
+
+###### **Arguments:**
+
+* `<NAME>` — Optional name to operate on
+
+   Longer description
+
+###### **Options:**
+
+* `-c`, `--config <FILE>` — Sets a custom config file
+* `--target <TARGET>`
+
+  Default value: `local`
+
+  Possible values:
+  - `local`:
+    Do the operation locally
+  - `remote`
+
+* `-d`, `--debug` — Turn debugging information on
+
+   Repeat this option to see more and more debug information.
+
+
+
+## `complex-app test`
+
+does testing things
+
+**Usage:** `complex-app test [OPTIONS]`
+
+###### **Options:**
+
+* `-l`, `--list` — lists test values
+
+
+
+## `complex-app only-hidden-options`
+
+Demo that `Options` is not printed if all options are hidden
+
+**Usage:** `complex-app only-hidden-options`
+
+
+

src/lib.rs

@@ -12,13 +12,57 @@ mod test_readme {
     #![doc = include_str!("../README.md")]
 }
 
-use std::{
-    default,
-    fmt::{self, Write},
-};
+use std::fmt::{self, Write};
 
 use clap::builder::PossibleValue;
 
+//======================================
+// Public API types
+//======================================
+
+/// Options to customize the structure of the output Markdown document.
+///
+/// Used with [`help_markdown_custom()`].
+#[non_exhaustive]
+pub struct MarkdownOptions {
+    title: Option<String>,
+    show_footer: bool,
+}
+
+impl MarkdownOptions {
+    /// Construct a default instance of `MarkdownOptions`.
+    pub fn new() -> Self {
+        return Self {
+            title: None,
+            show_footer: true,
+        };
+    }
+
+    /// Set a custom title to use in the generated document.
+    pub fn title(mut self, title: String) -> Self {
+        self.title = Some(title);
+
+        return self;
+    }
+
+    /// Whether to show the default footer advertising `clap-markdown`.
+    pub fn show_footer(mut self, show: bool) -> Self {
+        self.show_footer = show;
+
+        return self;
+    }
+}
+
+impl Default for MarkdownOptions {
+    fn default() -> Self {
+        return Self::new();
+    }
+}
+
+//======================================
+// Public API functions
+//======================================
+
 /// Format the help information for `command` as Markdown.
 pub fn help_markdown<C: clap::CommandFactory>() -> String {
     let command = C::command();
@@ -27,8 +71,8 @@ pub fn help_markdown<C: clap::CommandFactory>() -> String {
 }
 
 /// Format the help information for `command` as Markdown, with custom options.
-pub fn custom_help_markdown<C: clap::CommandFactory>(
-    options: MarkdownOptions,
+pub fn help_markdown_custom<C: clap::CommandFactory>(
+    options: &MarkdownOptions,
 ) -> String {
     let command = C::command();
 
@@ -43,7 +87,7 @@ pub fn custom_help_markdown<C: clap::CommandFactory>(
 pub fn help_markdown_command(command: &clap::Command) -> String {
     let mut buffer = String::with_capacity(100);
 
-    write_help_markdown(&mut buffer, command, default::Default::default());
+    write_help_markdown(&mut buffer, command, &Default::default());
 
     buffer
 }
@@ -60,21 +104,15 @@ pub fn print_help_markdown<C: clap::CommandFactory>() {
 
     let mut buffer = String::with_capacity(100);
 
-    write_help_markdown(&mut buffer, &command, default::Default::default());
+    write_help_markdown(&mut buffer, &command, &Default::default());
 
     println!("{}", buffer);
 }
 
-#[derive(Default)]
-pub struct MarkdownOptions {
-    pub title: Option<String>,
-    pub hide_footer: bool,
-}
-
 fn write_help_markdown(
     buffer: &mut String,
     command: &clap::Command,
-    options: MarkdownOptions,
+    options: &MarkdownOptions,
 ) {
     //----------------------------------
     // Write the document title
@@ -120,7 +158,7 @@ fn write_help_markdown(
     //-----------------
     // Write the footer
     //-----------------
-    if !options.hide_footer {
+    if options.show_footer {
         write!(buffer, r#"<hr/>
 
 <small><i>

tests/test_examples.rs

@@ -1,3 +1,4 @@
+use clap_markdown::MarkdownOptions;
 use pretty_assertions::assert_eq;
 
 #[test]
@@ -10,4 +11,14 @@ fn test_example_complex_app() {
         clap_markdown::help_markdown::<complex_app::Cli>(),
         include_str!("../docs/examples/complex-app.md")
     );
+
+    assert_eq!(
+        clap_markdown::help_markdown_custom::<complex_app::Cli>(
+            &MarkdownOptions::new()
+                .title(format!("Some Custom Title for Complex App"))
+                .show_footer(false)
+        ),
+        include_str!("../docs/examples/complex-app-custom.md"),
+        "Mismatch testing CUSTOM Markdown output"
+    );
 }