Skip to content

Commit

Permalink
Merge pull request #5121 from epage/docs
Browse files Browse the repository at this point in the history
docs(tutorial): Try to clean up the text
  • Loading branch information
epage authored Sep 12, 2023
2 parents 37ba607 + 9e7404b commit 20987de
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 12 deletions.
3 changes: 2 additions & 1 deletion examples/tutorial_builder/03_04_subcommands.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,8 @@ Options:

```

Because we set [`Command::propagate_version`][crate::Command::propagate_version]:
Since we specified [`Command::propagate_version`][crate::Command::propagate_version], the `--version` flag
is available in all subcommands:
```console
$ 03_04_subcommands --version
clap [..]
Expand Down
6 changes: 4 additions & 2 deletions examples/tutorial_derive/03_04_subcommands.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ $ 03_04_subcommands_derive add bob

```

Because we used `command: Commands` instead of `command: Option<Commands>`:
When specifying commands with `command: Commands`, they are required.
Alternatively, you could do `commaand: Option<Commands>` to make it optional.
```console
$ 03_04_subcommands_derive
? failed
Expand All @@ -47,7 +48,8 @@ Options:

```

Because we added `#[command(propagate_version = true)]`:
Since we specified [`#[command(propagate_version = true)]`][crate::Command::propagate_version],
the `--version` flag is available in all subcommands:
```console
$ 03_04_subcommands_derive --version
clap [..]
Expand Down
23 changes: 14 additions & 9 deletions src/_derive/_tutorial.rs
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,14 @@
//!
#![doc = include_str!("../../examples/tutorial_derive/02_apps.md")]
//!
//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] to fill these fields in from your `Cargo.toml` file.
//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] on the struct to fill these fields in from your `Cargo.toml` file.
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")]
//! ```
#![doc = include_str!("../../examples/tutorial_derive/02_crate.md")]
//!
//! You can use attributes to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
//! You can use `#[command]` attributes on the struct to change the application level behavior of clap. Any [`Command`][crate::Command] builder function can be used as an attribute, like [`Command::next_line_help`].
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")]
Expand All @@ -71,6 +71,8 @@
//!
//! ## Adding Arguments
//!
//! Arguments are inferred from the fields of your struct.
//!
//! ### Positionals
//!
//! You can have users specify values by their position on the command-line:
Expand All @@ -94,9 +96,9 @@
//! - They can be optional
//! - Intent is clearer
//!
//! The [`#[arg(short = 'n')]`][Arg::short] and [`#[arg(long = "name")]`][Arg::long] attributes that define
//! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value
//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]).
//! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
//! [`#[arg(long = "name")]`][Arg::long] attributes on a field. When no value is given (e.g.
//! `#[arg(short)]`), the flag is inferred from the field's name.
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")]
Expand Down Expand Up @@ -128,11 +130,14 @@
//! ```
#![doc = include_str!("../../examples/tutorial_derive/03_01_flag_count.md")]
//!
//! This also shows that any[`Arg`][crate::Args] method may be used as an attribute.
//!
//! ### Subcommands
//!
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via [`#[command(subcommand)]` attribute][super#command-attributes]. Each
//! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own
//! subcommands.
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via
//! [`#[command(subcommand)]` attribute][super#command-attributes] on the field using that type.
//! Each instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args,
//! and even its own subcommands.
//!
//! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")]
Expand Down Expand Up @@ -165,7 +170,7 @@
//!
//! For example, if you have arguments of specific values you want to test for, you can derive
//! [`ValueEnum`][super#valueenum-attributes]
//! (any [`PossibleValue`] builder function can be used as variant attributes).
//! (any [`PossibleValue`] builder function can be used as a `#[value]` attribute on enum variants).
//!
//! This allows you specify the valid values for that argument. If the user does not use one of
//! those specific values, they will receive a graceful exit with error message informing them
Expand Down

0 comments on commit 20987de

Please sign in to comment.