Search code examples
rustclap

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

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?

Solution

  • 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