Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2025-03-04 15:27:16 +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 ```console
$ 03_04_subcommands --version $ 03_04_subcommands --version
clap [..] 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 ```console
$ 03_04_subcommands_derive $ 03_04_subcommands_derive
? failed ? 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 ```console
$ 03_04_subcommands_derive --version $ 03_04_subcommands_derive --version
clap [..] clap [..]

21
src/_derive/_tutorial.rs
View file

@ -55,14 +55,14 @@
//! //!
#![doc = include_str!("../../examples/tutorial_derive/02_apps.md")] #![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 //! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")] #![doc = include_str!("../../examples/tutorial_derive/02_crate.rs")]
//! ``` //! ```
#![doc = include_str!("../../examples/tutorial_derive/02_crate.md")] #![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 //! ```rust
#![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")] #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")]
@ -71,6 +71,8 @@
//! //!
//! ## Adding Arguments //! ## Adding Arguments
//! //!
//! Arguments are inferred from the fields of your struct.
//!
//! ### Positionals //! ### Positionals
//! //!
//! You can have users specify values by their position on the command-line: //! You can have users specify values by their position on the command-line:
@ -94,9 +96,9 @@
//! - They can be optional //! - They can be optional
//! - Intent is clearer //! - Intent is clearer
//! //!
//! The [`#[arg(short = 'n')]`][Arg::short] and [`#[arg(long = "name")]`][Arg::long] attributes that define //! To specify the flags for an argument, you can use [`#[arg(short = 'n')]`][Arg::short] and/or
//! the flags are [`Arg`][crate::Args] methods that are derived from the field name when no value //! [`#[arg(long = "name")]`][Arg::long] attributes on a field. When no value is given (e.g.
//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]). //! `#[arg(short)]`), the flag is inferred from the field's name.
//! //!
//! ```rust //! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")] #![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")] #![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
//! //!
//! Subcommands are derived with `#[derive(Subcommand)]` and be added via [`#[command(subcommand)]` attribute][super#command-attributes]. Each //! Subcommands are derived with `#[derive(Subcommand)]` and be added via
//! instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args, and even its own //! [`#[command(subcommand)]` attribute][super#command-attributes] on the field using that type.
//! subcommands. //! Each instance of a [Subcommand][crate::Subcommand] can have its own version, author(s), Args,
//! and even its own subcommands.
//! //!
//! ```rust //! ```rust
#![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")] #![doc = include_str!("../../examples/tutorial_derive/03_04_subcommands.rs")]