Merge pull request #3278 from epage/about

docs(examples): Steer people to know about about vs long_about

README.md

@@ -37,7 +37,7 @@ use clap::Parser;
 
 /// Simple program to greet a person
 #[derive(Parser, Debug)]
-#[clap(about, version, author)]
+#[clap(author, version, about, long_about = None)]
 struct Args {
     /// Name of the person to greet
     #[clap(short, long)]

examples/cargo-example-derive.rs

@@ -8,7 +8,7 @@ enum Cargo {
 }
 
 #[derive(clap::Args)]
-#[clap(about, author, version)]
+#[clap(author, version, about, long_about = None)]
 struct ExampleDerive {
     #[clap(long, parse(from_os_str))]
     manifest_path: Option<std::path::PathBuf>,

examples/demo.rs

@@ -4,7 +4,7 @@ use clap::Parser;
 
 /// Simple program to greet a person
 #[derive(Parser, Debug)]
-#[clap(about, version, author)]
+#[clap(author, version, about, long_about = None)]
 struct Args {
     /// Name of the person to greet
     #[clap(short, long)]

examples/derive_ref/README.md

@@ -258,7 +258,7 @@ for individual arguments can be specified via [`Arg::help`] and [`Arg::long_help
 # use clap::Parser;
 
 #[derive(Parser)]
-#[clap(about = "I am a program and I work, just pass `-h`")]
+#[clap(about = "I am a program and I work, just pass `-h`", long_about = None)]
 struct Foo {
     #[clap(short, help = "Pass `-h` and you'll see me!")]
     bar: String,

examples/derive_ref/custom-bool.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser, Debug, PartialEq)]
-#[clap(about, author, version)]
+#[clap(author, version, about, long_about = None)]
 struct Opt {
     // Default parser for `try_from_str` is FromStr::from_str.
     // `impl FromStr for bool` parses `true` or `false` so this

examples/escaped-positional-derive.rs

@@ -3,7 +3,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(about, version, author)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(short = 'f')]
     eff: bool,

examples/git-derive.rs

@@ -8,7 +8,7 @@ use clap::{AppSettings, Parser, Subcommand};
 /// A fictional versioning CLI
 #[derive(Parser)]
 #[clap(name = "git")]
-#[clap(about = "A fictional versioning CLI")]
+#[clap(about = "A fictional versioning CLI", long_about = None)]
 struct Cli {
     #[clap(subcommand)]
     command: Commands,

examples/tutorial_derive/01_quick.rs

@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use clap::{Parser, Subcommand};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Optional name to operate on
     name: Option<String>,

examples/tutorial_derive/02_app_settings.rs

@@ -1,7 +1,7 @@
 use clap::{AppSettings, Parser};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 #[clap(global_setting(AppSettings::AllArgsOverrideSelf))]
 #[clap(global_setting(AppSettings::DeriveDisplayOrder))]
 #[clap(global_setting(AppSettings::AllowNegativeNumbers))]

examples/tutorial_derive/02_apps.rs

@@ -4,7 +4,7 @@ use clap::Parser;
 #[clap(name = "MyApp")]
 #[clap(author = "Kevin K. <kbknapp@gmail.com>")]
 #[clap(version = "1.0")]
-#[clap(about = "Does awesome things")]
+#[clap(about = "Does awesome things", long_about = None)]
 struct Cli {
     #[clap(long)]
     two: String,

examples/tutorial_derive/02_crate.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(long)]
     two: String,

examples/tutorial_derive/03_01_flag_bool.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(short, long)]
     verbose: bool,

examples/tutorial_derive/03_01_flag_count.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(short, long, parse(from_occurrences))]
     verbose: usize,

examples/tutorial_derive/03_02_option.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(short, long)]
     name: Option<String>,

examples/tutorial_derive/03_03_positional.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     name: Option<String>,
 }

examples/tutorial_derive/03_04_subcommands.rs

@@ -1,7 +1,7 @@
 use clap::{AppSettings, Parser, Subcommand};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 #[clap(global_setting(AppSettings::PropagateVersion))]
 #[clap(global_setting(AppSettings::UseLongFormatForHelpSubcommand))]
 struct Cli {

examples/tutorial_derive/03_05_default_values.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     #[clap(default_value_t = String::from("alice"))]
     name: String,

examples/tutorial_derive/04_01_enum.rs

@@ -1,7 +1,7 @@
 use clap::{ArgEnum, Parser};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     /// What mode to run the program in
     #[clap(arg_enum)]

examples/tutorial_derive/04_02_validate.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Network port to use
     #[clap(parse(try_from_str))]

examples/tutorial_derive/04_03_relations.rs

@@ -1,7 +1,7 @@
 use clap::{ArgGroup, Parser};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 #[clap(group(
             ArgGroup::new("vers")
                 .required(true)

examples/tutorial_derive/04_04_custom.rs

@@ -1,7 +1,7 @@
 use clap::{ErrorKind, IntoApp, Parser};
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     /// set version manually
     #[clap(long, value_name = "VER")]

examples/tutorial_derive/05_01_assert.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 
 #[derive(Parser)]
-#[clap(author, version, about)]
+#[clap(author, version, about, long_about = None)]
 struct Cli {
     /// Network port to use
     #[clap(parse(try_from_str))]