Documenting and writing helptext for Structopt CLI commands and flags

Chris Biscardi
InstructorChris Biscardi
Share this video with your friends

Social Share Links

Send Tweet
Published 3 years ago
Updated 3 years ago

if we run cargo run -- --help, we can see that structopt thinks the name of our binary is still the package name. We can change that with another attribute macro on our struct.

digital-garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write

Also notice that in the help text the help subcommand has some helpful output while write has none:

garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write

There are a number of places we can put doc comments. We can write on the Opt struct for global information about the CLI.

We can also write on each subcommand or even the options for each subcommand.

/// A CLI for the growing and curation of a digital garden
///
/// Visit https://www.rustadventure.rs/garden for more!
struct Opt {
    #[structopt(subcommand)]
    cmd: Command,
}
enum Command {
    /// write something in your garden
    ///
    /// This command will open your $EDITOR, wait for you
    /// to write something, and then save the file to your
    /// garden
    Write {
        /// Optionally set a title for what you are going to write about
        #[structopt(short, long)]
        title: Option<String>,
    },
}

Each of these results in documentation going to the relevant place in the CLI help text. Note especially that the first line of doc comment for subcommands is shown as "short" help text, while the full text is reserved for running --help directly on the subcommand.

❯ cargo run
garden 0.1.0
A CLI for the growing and curation of a digital garden

Visit https://www.rustadventure.rs/garden for more!

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write    write something in your garden
❯ cargo run -- write --help
garden-write 0.1.0
write something in your garden

This command will open your $EDITOR, wait for you to write something, and then save the file to your garden

USAGE:
    garden write [OPTIONS]

FLAGS:
    -h, --help
            Prints help information

    -V, --version
            Prints version information

OPTIONS:
    -t, --title <title>
            Optionally set a title for what you are going to write about

Also note that -h and --help are not the same thing when it comes to structopt.

Instructor: [0:00] If we run our binary with the help flag, we can see some documentation for the help command as well as the fact that our subcommand doesn't have any documentation. Also notice that the name of our binary in the help output is the package name, not the binary name. Let's start by fixing that.

[0:18] We can use the structopt attribute macro with the name argument set to "garden" to change this. Now, when we run help, we'll see "garden" as the output. If we want to write a little bit more about the CLI, we can use /// and see that whatever we write is output below the binary name and above the usage.

[0:39] We can also write documentation on the subcommand level. Here we can see that the documentation takes the first line of our comment and uses it as the short description under the subcommands. If we instead pass help to a subcommand, we can see that the full description is shown and that the binary name now has the right subcommand attached.

[1:04] We can keep doing the same and document our flags as well. Now we see that the t flag, or the title flag, with the right subcommand has the description "Optionally set a title for what you're about to write about."

[1:18] Note that --help and -h in structopt mean different things, and that -h will give us shorter, more compact output, while --h will give us longer output.

egghead
egghead
~ an hour ago

Member comments are a way for members to communicate, interact, and ask questions about a lesson.

The instructor or someone from the community might respond to your question Here are a few basic guidelines to commenting on egghead.io

Be on-Topic

Comments are for discussing a lesson. If you're having a general issue with the website functionality, please contact us at support@egghead.io.

Avoid meta-discussion

  • This was great!
  • This was horrible!
  • I didn't like this because it didn't match my skill level.
  • +1 It will likely be deleted as spam.

Code Problems?

Should be accompanied by code! Codesandbox or Stackblitz provide a way to share code and discuss it in context

Details and Context

Vague question? Vague answer. Any details and context you can provide will lure more interesting answers!

Markdown supported.
Become a member to join the discussionEnroll Today