How to add long-form subcommand documentation in a clap CLI?

Question

I'm using #[derive(Subcommand)] to introduce subcommands in my CLI:


#[derive(Debug, Subcommand)]
enum Commands {
    /// Create a new config file
    ///
    /// Line one
    ///    Line two
    Init,
}

However, the documentation in long form help mode ends up being distorted. More precisely, when running mycli init --help, I get the following documentation output:

Create a new config file

Line one

Line two

Is there a way to add delicately formatted subcommand documentation (in the same way long_about= works for the CLI overall?

score 1 · Accepted Answer · answered Jan 11 '23 at 22:21

You're looking for #[verbatim_doc_comment]:

#[derive(Debug, Subcommand)]
enum Commands {
    /// Create a new config file
    ///
    /// Line one
    ///    Line two
    #[command(verbatim_doc_comment)]
    Init,
}

Output:

Create a new config file

Line one
   Line two

Usage: cli init

Options:
  -h, --help
          Print help information (use `-h` for a summary)

playground

How to add long-form subcommand documentation in a clap CLI?

1 Answers1