Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-11-10 14:54:15 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs(tutorial): Attempt to clarify attributes

Browse source
This commit is contained in:
Ed Page 2023-09-11 20:50:12 -05:00
parent db97a2c5be
commit 9e7404b599
3 changed files with 19 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
examples/tutorial_builder/03_04_subcommands.md
View file

@ -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 [..]

6
examples/tutorial_derive/03_04_subcommands.md
View file

@ -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
@ -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 [..]

21
src/_derive/_tutorial.rs
View file

@ -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")]
@ -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:
@ -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")]
@ -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")]