test: More exhaustively test current name/bin_name/display_name handl…

…ing behavior

docs/CHANGELOG.md

@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+* Added `help_markdown_custom()` and `help_markdown_command_custom()`, for
+  customizing the built Markdown.
+
+  Supported customization options include:
+
+  - Contents of the command title header.
+  - Whether to show the footer explaining the documentation was generated with
+    `clap-markdown`.
+
 
 
 ## [0.1.3] - 2022-12-28

src/lib.rs

@@ -76,18 +76,22 @@ pub fn help_markdown_custom<C: clap::CommandFactory>(
 ) -> String {
     let command = C::command();
 
-    let mut buffer = String::with_capacity(100);
-
-    write_help_markdown(&mut buffer, &command, options);
-
-    buffer
+    return help_markdown_command_custom(&command, options);
 }
 
 /// Format the help information for `command` as Markdown.
 pub fn help_markdown_command(command: &clap::Command) -> String {
+    return help_markdown_command_custom(command, &Default::default());
+}
+
+/// Format the help information for `command` as Markdown, with custom options.
+pub fn help_markdown_command_custom(
+    command: &clap::Command,
+    options: &MarkdownOptions,
+) -> String {
     let mut buffer = String::with_capacity(100);
 
-    write_help_markdown(&mut buffer, command, &Default::default());
+    write_help_markdown(&mut buffer, &command, options);
 
     buffer
 }

tests/test_examples.rs

@@ -1,6 +1,8 @@
 use clap_markdown::MarkdownOptions;
 use pretty_assertions::assert_eq;
 
+/// Tests that the `complex-app` example featured in the README.md is
+/// up-to-date.
 #[test]
 fn test_example_complex_app() {
     mod complex_app {

tests/test_markdown.rs

@@ -0,0 +1,156 @@
+use clap::{Arg, Command};
+use clap_markdown::{help_markdown_command_custom, MarkdownOptions};
+
+use pretty_assertions::assert_eq;
+
+/// Test behavior for an app that defines a:
+///
+/// * `name`
+/// * `display_name`
+///
+/// but no custom `bin_name`.
+#[test]
+fn test_title_behavior_for_name_and_display_name_app() {
+    let mut app = Command::new("my-program-name")
+        // Note: Intentionally not setting custom bin name.
+        // .bin_name("my-program-bin-name")
+        .display_name("my-program-display-name")
+        .version("1.2.3")
+        .about("This program does things.")
+        .arg(Arg::new("foo").short('f'));
+    let () = app.build();
+
+    //-------------------------------------------------------------------
+    // Test the native behavior of `clap`, in terms of whether it prefers
+    // the `name`, `bin_name`, and `display_name` properties are used.
+    //-------------------------------------------------------------------
+
+    assert_eq!(
+        app.render_long_help().to_string(),
+        "\
+This program does things.
+
+Usage: my-program-name [OPTIONS]
+
+Options:
+  -f <foo>
+          
+
+  -h, --help
+          Print help information
+
+  -V, --version
+          Print version information
+"
+    );
+
+    //-------------------------------------------------------
+    // Test how clap-markdown handles the various name fields
+    //-------------------------------------------------------
+
+    assert_eq!(
+        help_markdown_command_custom(
+            &app,
+            &MarkdownOptions::new().show_footer(false)
+        ),
+        "\
+# Command-Line Help for my-program-display-name
+
+This document contains the help content for the `my-program-name` command-line program.
+
+**Command Overview:**
+
+* [`my-program-name`↴](#my-program-name)
+
+## `my-program-name`
+
+This program does things.
+
+**Usage:** `my-program-name [OPTIONS]`
+
+###### **Options:**
+
+* `-f <FOO>`
+* `-h`, `--help` — Print help information
+* `-V`, `--version` — Print version information
+
+
+
+"
+    );
+}
+
+/// Test behavior for an app that defines a:
+///
+/// * `name`
+/// * `bin_name`
+/// * `display_name`
+#[test]
+fn test_title_behavior_for_name_bin_name_and_display_name_app() {
+    let mut app = Command::new("my-program-name")
+        .bin_name("my-program-bin-name")
+        .display_name("my-program-display-name")
+        .version("1.2.3")
+        .about("This program does things.")
+        .arg(Arg::new("foo").short('f'));
+    let () = app.build();
+
+    //-------------------------------------------------------------------
+    // Test the native behavior of `clap`, in terms of whether it prefers
+    // the `name`, `bin_name`, and `display_name` properties are used.
+    //-------------------------------------------------------------------
+
+    assert_eq!(
+        app.render_long_help().to_string(),
+        "\
+This program does things.
+
+Usage: my-program-bin-name [OPTIONS]
+
+Options:
+  -f <foo>
+          
+
+  -h, --help
+          Print help information
+
+  -V, --version
+          Print version information
+"
+    );
+
+    //-------------------------------------------------------
+    // Test how clap-markdown handles the various name fields
+    //-------------------------------------------------------
+
+    assert_eq!(
+        help_markdown_command_custom(
+            &app,
+            &MarkdownOptions::new().show_footer(false)
+        ),
+        "\
+# Command-Line Help for my-program-display-name
+
+This document contains the help content for the `my-program-name` command-line program.
+
+**Command Overview:**
+
+* [`my-program-name`↴](#my-program-name)
+
+## `my-program-name`
+
+This program does things.
+
+**Usage:** `my-program-bin-name [OPTIONS]`
+
+###### **Options:**
+
+* `-f <FOO>`
+* `-h`, `--help` — Print help information
+* `-V`, `--version` — Print version information
+
+
+
+"
+    );
+}