mirror of
https://github.com/clap-rs/clap
synced 2024-12-13 22:32:33 +00:00
7e899cd340
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840 This is part of #16. clap-rs/clap#1840 wasn't the right call but we don't have time to make the decision now, so instead of having one option and changing it in 4.0, this reverts back to clap2 behavior.
74 lines
2.1 KiB
Rust
74 lines
2.1 KiB
Rust
//! How to use doc comments in place of `help/long_help`.
|
|
|
|
use clap::{Parser, Subcommand};
|
|
|
|
/// A basic example for the usage of doc comments as replacement
|
|
/// of the arguments `help`, `long_help`, `about` and `long_about`.
|
|
#[derive(Parser, Debug)]
|
|
#[clap(name = "basic")]
|
|
struct Opt {
|
|
/// Just use doc comments to replace `help`, `long_help`,
|
|
/// `about` or `long_about` input.
|
|
#[clap(short, long)]
|
|
first_flag: bool,
|
|
|
|
/// Split between `help` and `long_help`.
|
|
///
|
|
/// In the previous case clap is going to present
|
|
/// the whole comment both as text for the `help` and the
|
|
/// `long_help` argument.
|
|
///
|
|
/// But if the doc comment is formatted like this example
|
|
/// -- with an empty second line splitting the heading and
|
|
/// the rest of the comment -- only the first line is used
|
|
/// as `help` argument. The `long_help` argument will still
|
|
/// contain the whole comment.
|
|
///
|
|
/// ## Attention
|
|
///
|
|
/// Any formatting next to empty lines that could be used
|
|
/// inside a doc comment is currently not preserved. If
|
|
/// lists or other well formatted content is required it is
|
|
/// necessary to use the related clap argument with a
|
|
/// raw string as shown on the `third_flag` description.
|
|
#[clap(short, long)]
|
|
second_flag: bool,
|
|
|
|
#[clap(
|
|
short,
|
|
long,
|
|
long_help = r"This is a raw string.
|
|
|
|
It can be used to pass well formatted content (e.g. lists or source
|
|
code) in the description:
|
|
|
|
- first example list entry
|
|
- second example list entry
|
|
"
|
|
)]
|
|
third_flag: bool,
|
|
|
|
#[clap(subcommand)]
|
|
sub_command: SubCommand,
|
|
}
|
|
|
|
#[derive(Subcommand, Debug)]
|
|
#[clap()]
|
|
enum SubCommand {
|
|
/// The same rules described previously for flags. Are
|
|
/// also true for in regards of sub-commands.
|
|
First,
|
|
|
|
/// Applicable for both `about` an `help`.
|
|
///
|
|
/// The formatting rules described in the comment of the
|
|
/// `second_flag` also apply to the description of
|
|
/// sub-commands which is normally given through the `about`
|
|
/// and `long_about` arguments.
|
|
Second,
|
|
}
|
|
|
|
fn main() {
|
|
let opt = Opt::parse();
|
|
println!("{:?}", opt);
|
|
}
|