Prefer use of display_name wherever possible

src/lib.rs

@@ -12,7 +12,6 @@ mod test_readme {
     #![doc = include_str!("../README.md")]
 }
 
-
 use std::fmt::{self, Write};
 
 use clap::builder::PossibleValue;
@@ -28,7 +27,7 @@ pub fn help_markdown<C: clap::CommandFactory>() -> String {
 pub fn help_markdown_command(command: &clap::Command) -> String {
     let mut buffer = String::with_capacity(100);
 
-    write_help_markdown(&mut buffer, command);
+    write_help_markdown(&mut buffer, command, None);
 
     buffer
 }
@@ -40,32 +39,33 @@ pub fn help_markdown_command(command: &clap::Command) -> String {
 /// Format the help information for `command` as Markdown and print it.
 ///
 /// Output is printed to the standard output, using [`println!`].
-pub fn print_help_markdown<C: clap::CommandFactory>() {
+pub fn print_help_markdown<C: clap::CommandFactory>(disable_toc: Option<bool>) {
     let command = C::command();
 
     let mut buffer = String::with_capacity(100);
 
-    write_help_markdown(&mut buffer, &command);
+    write_help_markdown(&mut buffer, &command, disable_toc);
 
     println!("{}", buffer);
 }
 
-fn write_help_markdown(buffer: &mut String, command: &clap::Command) {
+fn write_help_markdown(
+    buffer: &mut String,
+    command: &clap::Command,
+    disable_toc: Option<bool>,
+) {
     //----------------------------------
     // Write the document title
     //----------------------------------
 
-    let title_name = match command.get_display_name() {
-        Some(display_name) => display_name.to_owned(),
-        None => format!("`{}`", command.get_name()),
-    };
+    let title_name = get_canonical_name(command);
 
     writeln!(buffer, "# Command-Line Help for {title_name}\n").unwrap();
 
     writeln!(
         buffer,
         "This document contains the help content for the `{}` command-line program.\n",
-        command.get_name()
+        title_name
     ).unwrap();
 
     //----------------------------------
@@ -76,11 +76,14 @@ fn write_help_markdown(buffer: &mut String, command: &clap::Command) {
     // build_table_of_contents_html(buffer, Vec::new(), command, 0).unwrap();
     // writeln!(buffer, "</ul></div>").unwrap();
 
-    writeln!(buffer, "**Command Overview:**\n").unwrap();
+    if let None = disable_toc {
+        writeln!(buffer, "**Command Overview:**\n").unwrap();
 
-    build_table_of_contents_markdown(buffer, Vec::new(), command, 0).unwrap();
+        build_table_of_contents_markdown(buffer, Vec::new(), command, 0)
+            .unwrap();
 
-    write!(buffer, "\n").unwrap();
+        write!(buffer, "\n").unwrap();
+    }
 
     //----------------------------------------
     // Write the commands/subcommands sections
@@ -114,10 +117,12 @@ fn build_table_of_contents_markdown(
         return Ok(());
     }
 
+    let title_name = get_canonical_name(command);
+
     // Append the name of `command` to `command_path`.
     let command_path = {
         let mut command_path = parent_command_path;
-        command_path.push(command.get_name().to_owned());
+        command_path.push(title_name);
         command_path
     };
 
@@ -202,10 +207,12 @@ fn build_command_markdown(
         return Ok(());
     }
 
+    let title_name = get_canonical_name(command);
+
     // Append the name of `command` to `command_path`.
     let command_path = {
         let mut command_path = parent_command_path.clone();
-        command_path.push(command.get_name().to_owned());
+        command_path.push(title_name);
         command_path
     };
 
@@ -270,10 +277,12 @@ fn build_command_markdown(
                 continue;
             }
 
+            let title_name = get_canonical_name(subcommand);
+
             writeln!(
                 buffer,
                 "* `{}` — {}",
-                subcommand.get_name(),
+                title_name,
                 match subcommand.get_about() {
                     Some(about) => about.to_string(),
                     None => String::new(),
@@ -460,3 +469,14 @@ fn write_arg_markdown(buffer: &mut String, arg: &clap::Arg) -> fmt::Result {
 
     Ok(())
 }
+
+// This is a utility function to get the canonical name of a command. It's logic is
+// to get the display name if it exists, otherwise get the bin name if it exists, otherwise
+// get the package name.
+fn get_canonical_name(command: &clap::Command) -> String {
+    command
+        .get_display_name()
+        .or_else(|| command.get_bin_name())
+        .map(|name| name.to_owned())
+        .unwrap_or_else(|| command.get_name().to_owned())
+}