Documenting and writing helptext for Structopt CLI commands and flags
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.