]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | //! How to use doc comments in place of `help/long_help`. |
2 | ||
3 | use structopt::StructOpt; | |
4 | ||
5 | /// A basic example for the usage of doc comments as replacement | |
6 | /// of the arguments `help`, `long_help`, `about` and `long_about`. | |
7 | #[derive(StructOpt, Debug)] | |
8 | #[structopt(name = "basic")] | |
9 | struct Opt { | |
10 | /// Just use doc comments to replace `help`, `long_help`, | |
11 | /// `about` or `long_about` input. | |
12 | #[structopt(short, long)] | |
13 | first_flag: bool, | |
14 | ||
15 | /// Split between `help` and `long_help`. | |
16 | /// | |
17 | /// In the previous case structopt is going to present | |
18 | /// the whole comment both as text for the `help` and the | |
19 | /// `long_help` argument. | |
20 | /// | |
21 | /// But if the doc comment is formatted like this example | |
22 | /// -- with an empty second line splitting the heading and | |
23 | /// the rest of the comment -- only the first line is used | |
24 | /// as `help` argument. The `long_help` argument will still | |
25 | /// contain the whole comment. | |
26 | /// | |
27 | /// ## Attention | |
28 | /// | |
29 | /// Any formatting next to empty lines that could be used | |
30 | /// inside a doc comment is currently not preserved. If | |
31 | /// lists or other well formatted content is required it is | |
32 | /// necessary to use the related structopt argument with a | |
33 | /// raw string as shown on the `third_flag` description. | |
34 | #[structopt(short, long)] | |
35 | second_flag: bool, | |
36 | ||
37 | #[structopt( | |
38 | short, | |
39 | long, | |
40 | long_help = r"This is a raw string. | |
41 | ||
42 | It can be used to pass well formatted content (e.g. lists or source | |
43 | code) in the description: | |
44 | ||
45 | - first example list entry | |
46 | - second example list entry | |
47 | " | |
48 | )] | |
49 | third_flag: bool, | |
50 | ||
51 | #[structopt(subcommand)] | |
52 | sub_command: SubCommand, | |
53 | } | |
54 | ||
55 | #[derive(StructOpt, Debug)] | |
56 | #[structopt()] | |
57 | enum SubCommand { | |
58 | /// The same rules described previously for flags. Are | |
59 | /// also true for in regards of sub-commands. | |
60 | First, | |
61 | ||
62 | /// Applicable for both `about` an `help`. | |
63 | /// | |
64 | /// The formatting rules described in the comment of the | |
65 | /// `second_flag` also apply to the description of | |
66 | /// sub-commands which is normally given through the `about` | |
67 | /// and `long_about` arguments. | |
68 | Second, | |
69 | } | |
70 | ||
71 | fn main() { | |
72 | let opt = Opt::from_args(); | |
73 | println!("{:?}", opt); | |
74 | } |