From 3ccde7a4b8f7a2ea8b916a5415c04a8ff4b5cb7a Mon Sep 17 00:00:00 2001 From: tormol Date: Sun, 9 Oct 2016 14:38:31 +0200 Subject: [PATCH] docs: reword docs for ErrorKind and app::Settings Also adds a blank line between variants and wraps markdown lines at punctuation when it makes sense. (Doesn't affect generated docs) --- src/app/settings.rs | 100 ++++++++++++++++++++++++++++---------------- src/errors.rs | 43 +++++++++++++------ 2 files changed, 94 insertions(+), 49 deletions(-) diff --git a/src/app/settings.rs b/src/app/settings.rs index 1f1e671c78e..97b2cebc5ec 100644 --- a/src/app/settings.rs +++ b/src/app/settings.rs @@ -94,11 +94,11 @@ impl AppFlags { /// [`App`]: ./struct.App.html #[derive(Debug, PartialEq, Copy, Clone)] pub enum AppSettings { - /// Allows [`SubCommand`]s to override all requirements of the parent command. For example if you - /// had a subcommand or top level application which had a required argument that are only - /// required as long as there is no subcommand present, using this setting would allow you set - /// those arguments to [`Arg::required(true)`] and yet receive no error so long as the user - /// uses a valid subcommand instead. + /// Allows [`SubCommand`]s to override all requirements of the parent command. + /// For example if you had a subcommand or top level application with a required argument + /// that is only required as long as there is no subcommand present, + /// using this setting would allow you to set those arguments to [`Arg::required(true)`] + /// and yet receive no error so long as the user uses a valid subcommand instead. /// /// **NOTE:** This defaults to false (using subcommand does *not* negate requirements) /// @@ -138,8 +138,9 @@ pub enum AppSettings { /// [`Arg::required(true)`]: ./struct.Arg.html#method.required /// [`SubCommand`]: ./struct.SubCommand.html SubcommandsNegateReqs, - /// Allows specifying that if no [`SubCommand`] is present at runtime, error and exit - /// gracefully + + /// Allows specifying that if no [`SubCommand`] is present at runtime, + /// error and exit gracefully. /// /// **NOTE:** This defaults to `false` (subcommands do *not* need to be present) /// @@ -159,8 +160,9 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html SubcommandRequired, - /// Specifies that the help text should be displayed (and then exit gracefully), if no - /// arguments are present at runtime (i.e. an empty run such as, `$ myprog`. + + /// Specifies that the help text should be displayed (and then exit gracefully), + /// if no arguments are present at runtime (i.e. an empty run such as, `$ myprog`. /// /// **NOTE:** [`SubCommand`]s count as arguments /// @@ -174,8 +176,9 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html ArgRequiredElseHelp, - /// Specifies to use the version of the current command for all child [`SubCommand`]. (Defaults - /// to `false`; subcommands have independant version strings from their parents) + + /// Specifies to use the version of the current command for all child [`SubCommand`]s. + /// (Defaults to `false`; subcommands have independant version strings from their parents.) /// /// **NOTE:** The version for the current command **and** this setting must be set **prior** to /// adding any child subcommands @@ -194,8 +197,9 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html GlobalVersion, - /// Disables `-V` and `--version` for all [`SubCommand`]s (Defaults to `false`; subcommands - /// *do* have version flags) + + /// Disables `-V` and `--version` for all [`SubCommand`]s + /// (Defaults to `false`; subcommands *do* have version flags.) /// /// **NOTE:** This setting must be set **prior** adding any subcommands /// @@ -215,8 +219,9 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html VersionlessSubcommands, - /// Groups flags and options together presenting a more unified help message (a la `getopts` or - /// `docopt` style). + + /// Groups flags and options together, presenting a more unified help message + /// (a la `getopts` or `docopt` style). /// /// The default is that the auto-generated help message will group flags, and options /// separately. @@ -233,6 +238,7 @@ pub enum AppSettings { /// // running `myprog --help` will display a unified "docopt" or "getopts" style help message /// ``` UnifiedHelpMessage, + /// Will display a message "Press [ENTER]/[RETURN] to continue..." and wait for user before /// exiting /// @@ -254,8 +260,9 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html WaitOnError, - /// Specifies that the help text should be displayed (and then exit gracefully), if no - /// [`SubCommand`]s are present at runtime (i.e. an empty run such as, `$ myprog`. + + /// Specifies that the help text should be displayed (before exiting gracefully) if no + /// [`SubCommand`]s are present at runtime (i.e. an empty run such as `$ myprog`). /// /// **NOTE:** This should *not* be used with [`AppSettings::SubcommandRequired`] as they do /// nearly same thing; this prints the help text, and the other prints an error. @@ -276,6 +283,7 @@ pub enum AppSettings { /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp SubcommandRequiredElseHelp, + /// Specifies that this [`SubCommand`] should be hidden from help messages /// /// # Examples @@ -289,6 +297,7 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html Hidden, + /// Specifies that the final positional argument is a "VarArg" and that `clap` should not /// attempt to parse any further args. /// @@ -311,6 +320,7 @@ pub enum AppSettings { /// ``` /// [`Arg::multiple(true)`]: ./struct.Arg.html#method.multiple TrailingVarArg, + /// Specifies that the parser should not assume the first argument passed is the binary name. /// This is normally the case when using a "daemon" style mode, or an interactive CLI where one /// one would not normally type the binary or program name for each command. @@ -328,14 +338,15 @@ pub enum AppSettings { /// assert_eq!(cmds, ["command", "set"]); /// ``` NoBinaryName, - /// Specifies that an unexpected positional argument, which would otherwise cause a - /// [`ErrorKind::UnknownArgument`] error, should instead be treated as a [`SubCommand`] within - /// the [`ArgMatches`] struct. + + /// Specifies that an unexpected positional argument, + /// which would otherwise cause a [`ErrorKind::UnknownArgument`] error, + /// should instead be treated as a [`SubCommand`] within the [`ArgMatches`] struct. /// - /// **NOTE:** Use this setting with caution, as a truly unexpected argument (i.e. one that is - /// *NOT* an external subcommand) will **not** cause an error and instead be treated as a - /// potential subcommand. One should check for such cases manually and inform the user - /// appropriately. + /// **NOTE:** Use this setting with caution, + /// as a truly unexpected argument (i.e. one that is *NOT* an external subcommand) + /// will **not** cause an error and instead be treated as a potential subcommand. + /// One should check for such cases manually and inform the user appropriately. /// /// # Examples /// @@ -363,10 +374,11 @@ pub enum AppSettings { /// [`SubCommand`]: ./struct.SubCommand.html /// [`ArgMatches`]: ./struct.ArgMatches.html AllowExternalSubcommands, + /// Specifies that any invalid UTF-8 code points should be treated as an error and fail /// with a [`ErrorKind::InvalidUtf8`] error. /// - /// **NOTE:** This rule only applies to argument values. Things such as flags, options, and + /// **NOTE:** This rule only applies to argument values; Things such as flags, options, and /// [`SubCommand`]s themselves only allow valid UTF-8 code points. /// /// # Platform Specific @@ -395,8 +407,9 @@ pub enum AppSettings { /// [`SubCommand`]: ./struct.SubCommand.html /// [`ErrorKind::InvalidUtf8`]: ./enum.ErrorKind.html#variant.InvalidUtf8 StrictUtf8, - /// Specifies that any invalid UTF-8 code points should *not* be treated as an error. This is - /// the default behavior of `clap` + + /// Specifies that any invalid UTF-8 code points should *not* be treated as an error. + /// This is the default behavior of `clap`. /// /// **NOTE:** Using argument values with invalid UTF-8 code points requires using /// [`ArgMatches::os_value_of`], [`ArgMatches::os_values_of`], [`ArgMatches::lossy_value_of`], @@ -435,8 +448,9 @@ pub enum AppSettings { /// [`ArgMatches::lossy_value_of`]: ./struct.ArgMatches.html#method.lossy_value_of /// [`ArgMatches::lossy_values_of`]: ./struct.ArgMatches.html#method.lossy_values_of AllowInvalidUtf8, + /// Specifies that leading hyphens are allowed in argument *values*, such as negative numbers - /// `-10` (which would otherwise be parsed as another flag or option) + /// like `-10`. (which would otherwise be parsed as another flag or option) /// /// **NOTE:** This can only be set application wide and not on a per argument basis. /// @@ -460,10 +474,12 @@ pub enum AppSettings { /// # ; /// ``` AllowLeadingHyphen, - /// Tells `clap` *not* to print possible values when displaying help information. This can be - /// useful if there are many values, or they are explained elsewhere. + + /// Tells `clap` *not* to print possible values when displaying help information. + /// This can be useful if there are many values, or they are explained elsewhere. HidePossibleValuesInHelp, - /// Places the help string for all arguments on the line after the argument + + /// Places the help string for all arguments on the line after the argument. /// /// # Examples /// @@ -474,8 +490,9 @@ pub enum AppSettings { /// .get_matches(); /// ``` NextLineHelp, + /// Displays the arguments and [`SubCommand`]s in the help message in the order that they were - /// declared in, vice alphabetically which is the default. + /// declared in, and not alphabetically which is the default. /// /// # Examples /// @@ -487,6 +504,7 @@ pub enum AppSettings { /// ``` /// [`SubCommand`]: ./struct.SubCommand.html DeriveDisplayOrder, + /// Uses colorized help messages. /// /// **NOTE:** Must be compiled with the `color` cargo feature @@ -504,15 +522,16 @@ pub enum AppSettings { /// .get_matches(); /// ``` ColoredHelp, + /// Enables colored output only when the output is going to a terminal or TTY. /// - /// **NOTE:** This is the default behavior of `clap` + /// **NOTE:** This is the default behavior of `clap`. /// - /// **NOTE:** Must be compiled with the `color` cargo feature + /// **NOTE:** Must be compiled with the `color` cargo feature. /// /// # Platform Specific /// - /// This setting only applies to Unix, Linux, and OSX (i.e. non-Windows platforms) + /// This setting only applies to Unix, Linux, and OSX (i.e. non-Windows platforms). /// /// # Examples /// @@ -523,13 +542,14 @@ pub enum AppSettings { /// .get_matches(); /// ``` ColorAuto, + /// Enables colored output regardless of whether or not the output is going to a terminal/TTY. /// - /// **NOTE:** Must be compiled with the `color` cargo feature + /// **NOTE:** Must be compiled with the `color` cargo feature. /// /// # Platform Specific /// - /// This setting only applies to Unix, Linux, and OSX (i.e. non-Windows platforms) + /// This setting only applies to Unix, Linux, and OSX (i.e. non-Windows platforms). /// /// # Examples /// @@ -540,6 +560,7 @@ pub enum AppSettings { /// .get_matches(); /// ``` ColorAlways, + /// Disables colored output no matter if the output is going to a terminal/TTY, or not. /// /// **NOTE:** Must be compiled with the `color` cargo feature @@ -557,6 +578,7 @@ pub enum AppSettings { /// .get_matches(); /// ``` ColorNever, + /// Disables the automatic delimiting of values when `--` or [`AppSettings::TrailingVarArg`] /// was used. /// @@ -575,12 +597,16 @@ pub enum AppSettings { /// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg /// [`Arg::use_delimiter(false)`]: ./struct.Arg.html#method.use_delimiter DontDelimitTrailingValues, + #[doc(hidden)] NeedsLongVersion, + #[doc(hidden)] NeedsLongHelp, + #[doc(hidden)] NeedsSubcommandHelp, + /// Disables `-V` and `--version` [`App`] without affecting any of the [`SubCommand`]s /// (Defaults to `false`; application *does* have a version flag) /// diff --git a/src/errors.rs b/src/errors.rs index 4046757b9c6..bb732249f94 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -19,8 +19,8 @@ pub type Result = StdResult; /// Command line argument parser kind of error #[derive(Debug, Copy, Clone, PartialEq)] pub enum ErrorKind { - /// Occurs when an [`Arg`] has a set of possible values, and the user provides a value which - /// isn't in that set. + /// Occurs when an [`Arg`] has a set of possible values, + /// and the user provides a value which isn't in that set. /// /// # Examples /// @@ -36,6 +36,7 @@ pub enum ErrorKind { /// ``` /// [`Arg`]: ./struct.Arg.html InvalidValue, + /// Occurs when a user provides a flag, option, argument or subcommand which isn't defined. /// /// # Examples @@ -49,6 +50,7 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnknownArgument); /// ``` UnknownArgument, + /// Occurs when the user provides an unrecognized [`SubCommand`] which meets the threshold for /// being similar enough to an existing subcommand. /// If it doesn't meet the threshold, or the 'suggestions' feature is disabled, @@ -72,6 +74,7 @@ pub enum ErrorKind { /// [`SubCommand`]: ./struct.SubCommand.html /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument InvalidSubcommand, + /// Occurs when the user provides an unrecognized [`SubCommand`] which either /// doesn't meet the threshold for being similar enough to an existing subcommand, /// or the 'sggestions' feature is disabled. @@ -98,6 +101,7 @@ pub enum ErrorKind { /// [`InvalidSubcommand`]: ./enum.ErrorKind.html#variant.InvalidSubcommand /// [`UnknownArgument`]: ./enum.ErrorKind.html#variant.UnknownArgument UnrecognizedSubcommand, + /// Occurs when the user provides an empty value for an option that does not allow empty /// values. /// @@ -114,6 +118,7 @@ pub enum ErrorKind { /// assert_eq!(res.unwrap_err().kind, ErrorKind::EmptyValue); /// ``` EmptyValue, + /// Occurs when the user provides a value for an argument with a custom validation and the /// value fails that validation. /// @@ -136,6 +141,7 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::ValueValidation); /// ``` ValueValidation, + /// Occurs when a user provides more values for an argument than were defined by setting /// [`Arg::max_values`]. /// @@ -153,6 +159,7 @@ pub enum ErrorKind { /// ``` /// [`Arg::max_values`]: ./struct.Arg.html#method.max_values TooManyValues, + /// Occurs when the user provides fewer values for an argument than were defined by setting /// [`Arg::min_values`]. /// @@ -170,6 +177,7 @@ pub enum ErrorKind { /// ``` /// [`Arg::min_values`]: ./struct.Arg.html#method.min_values TooFewValues, + /// Occurs when the user provides a different number of values for an argument than what's /// been defined by setting [`Arg::number_of_values`] or than was implicitly set by /// [`Arg::value_names`]. @@ -191,6 +199,7 @@ pub enum ErrorKind { /// [`Arg::number_of_values`]: ./struct.Arg.html#method.number_of_values /// [`Arg::value_names`]: ./struct.Arg.html#method.value_names WrongNumberOfValues, + /// Occurs when the user provides two values which conflict with each other and can't be used /// together. /// @@ -209,6 +218,7 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::ArgumentConflict); /// ``` ArgumentConflict, + /// Occurs when the user does not provide one or more required arguments. /// /// # Examples @@ -223,6 +233,7 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::MissingRequiredArgument); /// ``` MissingRequiredArgument, + /// Occurs when a subcommand is required (as defined by [`AppSettings::SubcommandRequired`]), /// but the user does not provide one. /// @@ -242,8 +253,9 @@ pub enum ErrorKind { /// ``` /// [`AppSettings::SubcommandRequired`]: ./enum.AppSettings.html#variant.SubcommandRequired MissingSubcommand, + /// Occurs when either an argument or [`SubCommand`] is required, as defined by - /// [`AppSettings::ArgRequiredElseHelp`] but the user did not provide one. + /// [`AppSettings::ArgRequiredElseHelp`], but the user did not provide one. /// /// # Examples /// @@ -262,8 +274,8 @@ pub enum ErrorKind { /// [`SubCommand`]: ./struct.SubCommand.html /// [`AppSettings::ArgRequiredElseHelp`]: ./enum.AppSettings.html#variant.ArgRequiredElseHelp MissingArgumentOrSubcommand, - /// Occurs when the user provides an argument multiple times which has not been set to allow - /// multiple uses. + + /// Occurs when the user provides multiple values to an argument which doesn't allow that. /// /// # Examples /// @@ -278,6 +290,7 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::UnexpectedMultipleUsage); /// ``` UnexpectedMultipleUsage, + /// Occurs when the user provides a value containing invalid UTF-8 for an argument and /// [`AppSettings::StrictUtf8`] is set. /// @@ -305,8 +318,9 @@ pub enum ErrorKind { /// ``` /// [`AppSettings::StrictUtf8`]: ./enum.AppSettings.html#variant.StrictUtf8 InvalidUtf8, - /// Not a true "error" as it means `--help` or similar was used. The help message will be sent - /// to `stdout`. + + /// Not a true "error" as it means `--help` or similar was used. + /// The help message will be sent to `stdout`. /// /// **Note**: If the help is displayed due to an error (such as missing subcommands) it will /// be sent to `stderr` instead of `stdout`. @@ -321,8 +335,9 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::HelpDisplayed); /// ``` HelpDisplayed, - /// Not a true "error" as it means `--version` or similar was used. The message will be sent - /// to `stdout`. + + /// Not a true "error" as it means `--version` or similar was used. + /// The message will be sent to `stdout`. /// /// # Examples /// @@ -334,17 +349,21 @@ pub enum ErrorKind { /// assert_eq!(result.unwrap_err().kind, ErrorKind::VersionDisplayed); /// ``` VersionDisplayed, + /// Occurs when using the [`value_t!`] and [`values_t!`] macros to convert an argument value /// into type `T`, but the argument you requested wasn't used. I.e. you asked for an argument /// with name `config` to be converted, but `config` wasn't used by the user. /// [`value_t!`]: ./macro.value_t!.html /// [`values_t!`]: ./macro.values_t!.html ArgumentNotFound, - /// Represents an [I/O error], typically while writing to `stderr` or `stdout`. + + /// Represents an [I/O error]. + /// Can occur when writing to `stderr` or `stdout` or reading a configuration file. /// [I/O error]: https://doc.rust-lang.org/std/io/struct.Error.html Io, - /// Represents an Rust's [Format error] as part of [`Display`] , typically while writing to - /// `stderr` or `stdout`. + + /// Represents a [Format error] (which is a part of [`Display`]). + /// Typically caused by writing to `stderr` or `stdout`. /// [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html /// [Format error]: https://doc.rust-lang.org/std/fmt/struct.Error.html Format,