From 975eb0c6864bc65e3dad8f1ada5be2c1db53c25b Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 23 Jun 2023 16:09:52 -0500 Subject: [PATCH] docs(tutorial): Link out to other docs more This is another step for trying to improve the understanding that the derive and builder APIs are linked (#4090). This also adds links to make it easier to discover more details on how we infer behavior from a field's type. --- src/_derive/_tutorial.rs | 36 ++++++++++++++++++------------------ src/_tutorial.rs | 17 ++++++++++++----- 2 files changed, 30 insertions(+), 23 deletions(-) diff --git a/src/_derive/_tutorial.rs b/src/_derive/_tutorial.rs index e3263802dfb..2a9145fa2f5 100644 --- a/src/_derive/_tutorial.rs +++ b/src/_derive/_tutorial.rs @@ -55,14 +55,14 @@ //! #![doc = include_str!("../../examples/tutorial_derive/02_apps.md")] //! -//! You can use `#[command(author, version, about)]` attribute defaults to fill these fields in from your `Cargo.toml` file. +//! You can use [`#[command(author, version, about)]` attribute defaults][super#command-attributes] 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. +//! 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`]. //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/02_app_settings.rs")] @@ -80,8 +80,8 @@ //! ``` #![doc = include_str!("../../examples/tutorial_derive/03_03_positional.md")] //! -//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple values, use [`Append`][crate::ArgAction::Append] via `Vec`: +//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To +//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`: //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_03_positional_mult.rs")] //! ``` @@ -94,17 +94,17 @@ //! - They can be optional //! - Intent is clearer //! -//! The `#[arg(short = 'n')]` and `#[arg(long = "name")]` attributes that define +//! 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)]`). +//! is specified ([`#[arg(short)]` and `#[arg(long)]`][super#arg-attributes]). //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_02_option.rs")] //! ``` #![doc = include_str!("../../examples/tutorial_derive/03_02_option.md")] //! -//! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append] via `Vec`: +//! Note that the [default `ArgAction` is `Set`][super#arg-types]. To +//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append] via `Vec`: //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_02_option_mult.rs")] //! ``` @@ -112,17 +112,15 @@ //! //! ### Flags //! -//! Flags can also be switches that can be on/off. This is enabled via the -//! `#[arg(action = ArgAction::SetTrue)]` attribute though this is implied when the field is a -//! `bool`. +//! Flags can also be switches that can be on/off: //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.rs")] //! ``` #![doc = include_str!("../../examples/tutorial_derive/03_01_flag_bool.md")] //! -//! Note that the default [`ArgAction`][crate::ArgAction] for a `bool` field is -//! [`SetTrue`][crate::ArgAction::SetTrue]. To accept multiple flags, use +//! Note that the [default `ArgAction` for a `bool` field is +//! `SetTrue`][super#arg-types]. To accept multiple flags, override the [action][Arg::action] with //! [`Count`][crate::ArgAction::Count]: //! //! ```rust @@ -132,7 +130,7 @@ //! //! ### Subcommands //! -//! Subcommands are derived with `#[derive(Subcommand)]` and be added via `#[command(subcommand)]` attribute. Each +//! 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. //! @@ -151,7 +149,7 @@ //! //! We've previously showed that arguments can be [`required`][crate::Arg::required] or optional. //! When optional, you work with a `Option` and can `unwrap_or`. Alternatively, you can -//! set `#[arg(default_value_t)]`. +//! set [`#[arg(default_value_t)]`][super#arg-attributes]. //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/03_05_default_values.rs")] @@ -166,7 +164,8 @@ //! ### Enumerated values //! //! For example, if you have arguments of specific values you want to test for, you can derive -//! [`ValueEnum`][crate::ValueEnum]. +//! [`ValueEnum`][super#valueenum-attributes] +//! (any [`PossibleValue`] builder function can be used as variant attributes). //! //! 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 @@ -179,14 +178,14 @@ //! //! ### Validated values //! -//! More generally, you can validate and parse into any data type. +//! More generally, you can validate and parse into any data type with [`Arg::value_parser`]. //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.rs")] //! ``` #![doc = include_str!("../../examples/tutorial_derive/04_02_parse.md")] //! -//! A custom parser can be used to improve the error messages or provide additional validation: +//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation: //! //! ```rust #![doc = include_str!("../../examples/tutorial_derive/04_02_validate.rs")] @@ -248,3 +247,4 @@ use crate::builder::Arg; use crate::builder::ArgGroup; use crate::builder::Command; use crate::builder::PossibleValue; +use crate::builder::TypedValueParser; diff --git a/src/_tutorial.rs b/src/_tutorial.rs index 09a23fe0efb..58e527cbc28 100644 --- a/src/_tutorial.rs +++ b/src/_tutorial.rs @@ -63,7 +63,7 @@ #![doc = include_str!("../examples/tutorial_builder/02_crate.md")] //! //! You can use [`Command`][crate::Command] methods to change the application level behavior of -//! clap. +//! clap, like [`Command::next_line_help`]. //! //! ```rust #![doc = include_str!("../examples/tutorial_builder/02_app_settings.rs")] @@ -82,7 +82,7 @@ #![doc = include_str!("../examples/tutorial_builder/03_03_positional.md")] //! //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple values, use [`Append`][crate::ArgAction::Append]: +//! accept multiple values, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]: //! ```rust #![doc = include_str!("../examples/tutorial_builder/03_03_positional_mult.rs")] //! ``` @@ -101,7 +101,7 @@ #![doc = include_str!("../examples/tutorial_builder/03_02_option.md")] //! //! Note that the default [`ArgAction`][crate::ArgAction] is [`Set`][crate::ArgAction::Set]. To -//! accept multiple occurrences, use [`Append`][crate::ArgAction::Append]: +//! accept multiple occurrences, override the [action][Arg::action] with [`Append`][crate::ArgAction::Append]: //! ```rust #![doc = include_str!("../examples/tutorial_builder/03_02_option_mult.rs")] //! ``` @@ -175,14 +175,14 @@ //! //! ### Validated values //! -//! More generally, you can validate and parse into any data type. +//! More generally, you can validate and parse into any data type with [`Arg::value_parser`]. //! //! ```rust #![doc = include_str!("../examples/tutorial_builder/04_02_parse.rs")] //! ``` #![doc = include_str!("../examples/tutorial_builder/04_02_parse.md")] //! -//! A custom parser can be used to improve the error messages or provide additional validation: +//! A [custom parser][TypedValueParser] can be used to improve the error messages or provide additional validation: //! //! ```rust #![doc = include_str!("../examples/tutorial_builder/04_02_validate.rs")] @@ -233,3 +233,10 @@ //! - Explore more features in the [API reference][super] //! //! For support, see [Discussions](https://github.com/clap-rs/clap/discussions) + +#![allow(unused_imports)] +use crate::builder::Arg; +use crate::builder::ArgGroup; +use crate::builder::Command; +use crate::builder::PossibleValue; +use crate::builder::TypedValueParser;