Merge pull request #4790 from epage/doc

doc: Clean up cfgs
clap-rs · Mar 27, 2023 · 615c1dc · 615c1dc
2 parents 57d1c39 + d9a641b
commit 615c1dc
Show file tree

Hide file tree

Showing 15 changed files with 127 additions and 90 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -77,7 +77,7 @@ Note: We have not yet determined the End-of-Life schedule for previous major ver
 ### Verifying Changes
 
 A common (sub)set of commands for verifying your change:
-```sh
+```console
 $ make test-full
 $ make clippy-full
 $ make doc

diff --git a/clap_complete/examples/completion-derive.rs b/clap_complete/examples/completion-derive.rs
@@ -1,16 +1,16 @@
 //! How to use value hints and generate shell completions.
 //!
 //! Usage with zsh:
-//! ```sh
-//! cargo run --example completion-derive -- --generate=zsh > /usr/local/share/zsh/site-functions/_completion_derive
-//! compinit
-//! ./target/debug/examples/completion_derive --<TAB>
+//! ```console
+//! $ cargo run --example completion-derive -- --generate=zsh > /usr/local/share/zsh/site-functions/_completion_derive
+//! $ compinit
+//! $ ./target/debug/examples/completion_derive --<TAB>
 //! ```
 //! fish:
-//! ```sh
-//! cargo run --example completion-derive -- --generate=fish > completion_derive.fish
-//! . ./completion_derive.fish
-//! ./target/debug/examples/completion_derive --<TAB>
+//! ```console
+//! $ cargo run --example completion-derive -- --generate=fish > completion_derive.fish
+//! $ . ./completion_derive.fish
+//! $ ./target/debug/examples/completion_derive --<TAB>
 //! ```
 use clap::{Args, Command, CommandFactory, Parser, Subcommand, ValueHint};
 use clap_complete::{generate, Generator, Shell};

diff --git a/clap_complete/examples/completion.rs b/clap_complete/examples/completion.rs
@@ -1,16 +1,16 @@
 //! Example to test arguments with different ValueHint values.
 //!
 //! Usage with zsh:
-//! ```sh
-//! cargo run --example completion -- --generate=zsh > /usr/local/share/zsh/site-functions/_completion
-//! compinit
-//! ./target/debug/examples/completion --<TAB>
+//! ```console
+//! $ cargo run --example completion -- --generate=zsh > /usr/local/share/zsh/site-functions/_completion$
+//! $ compinit
+//! $ ./target/debug/examples/completion --<TAB>
 //! ```
 //! fish:
-//! ```sh
-//! cargo run --example completion -- --generate=fish > completion.fish
-//! . ./completion.fish
-//! ./target/debug/examples/completion --<TAB>
+//! ```console
+//! $ cargo run --example completion -- --generate=fish > completion.fish
+//! $ . ./completion.fish
+//! $ ./target/debug/examples/completion --<TAB>
 //! ```
 use clap::{value_parser, Arg, Command, ValueHint};
 use clap_complete::{generate, Generator, Shell};

diff --git a/clap_complete/src/generator/mod.rs b/clap_complete/src/generator/mod.rs
@@ -217,7 +217,7 @@ where
 ///
 /// Usage:
 ///
-/// ```shell
+/// ```console
 /// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash
 /// ```
 pub fn generate<G, S>(gen: G, cmd: &mut clap::Command, bin_name: S, buf: &mut dyn Write)

diff --git a/src/builder/action.rs b/src/builder/action.rs
@@ -2,8 +2,8 @@
 ///
 /// # Examples
 ///
-#[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-#[cfg_attr(feature = "help", doc = " ```")]
+/// ```rust
+/// # #[cfg(feature = "help")] {
 /// # use clap::Command;
 /// # use clap::Arg;
 /// let cmd = Command::new("mycmd")
@@ -20,6 +20,7 @@
 /// // New help available
 /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
 /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
+/// # }
 /// ```
 #[derive(Clone, Debug)]
 #[non_exhaustive]
@@ -224,8 +225,8 @@ pub enum ArgAction {
     ///
     /// # Examples
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::Command;
     /// # use clap::Arg;
     /// let cmd = Command::new("mycmd")
@@ -242,6 +243,7 @@ pub enum ArgAction {
     /// // New help available
     /// let err = cmd.try_get_matches_from(["mycmd", "-?"]).unwrap_err();
     /// assert_eq!(err.kind(), clap::error::ErrorKind::DisplayHelp);
+    /// # }
     /// ```
     Help,
     /// When encountered, display [`Command::version`][super::Command::version]

diff --git a/src/builder/arg.rs b/src/builder/arg.rs
@@ -1125,8 +1125,8 @@ impl Arg {
     /// # ;
     /// ```
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("config")
@@ -1136,6 +1136,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     /// Running the above program produces the following output
     ///
@@ -1187,8 +1188,8 @@ impl Arg {
     ///     .value_names(["fast", "slow"]);
     /// ```
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("io")
@@ -1197,6 +1198,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// Running the above program produces the following output
@@ -2013,8 +2015,8 @@ impl Arg {
     /// Setting `help` displays a short message to the side of the argument when the user passes
     /// `-h` or `--help` (by default).
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2023,6 +2025,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays
@@ -2063,8 +2066,8 @@ impl Arg {
     /// Setting `help` displays a short message to the side of the argument when the user passes
     /// `-h` or `--help` (by default).
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2077,6 +2080,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays
@@ -2121,8 +2125,8 @@ impl Arg {
     ///
     /// # Examples
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg, ArgAction};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("a") // Typically args are grouped alphabetically by name.
@@ -2144,6 +2148,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays the following help message
@@ -2188,8 +2193,8 @@ impl Arg {
     ///
     /// # Examples
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg, ArgAction};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("opt")
@@ -2204,6 +2209,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays the following help message
@@ -2239,8 +2245,8 @@ impl Arg {
     ///
     /// Setting `Hidden` will hide the argument when displaying help text
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2250,6 +2256,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays
@@ -2413,8 +2420,8 @@ impl Arg {
     ///
     /// Setting `hide_short_help(true)` will hide the argument when displaying short help text
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2424,6 +2431,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "-h"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays
@@ -2440,8 +2448,8 @@ impl Arg {
     ///
     /// However, when --help is called
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2451,6 +2459,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// Then the following would be displayed
@@ -2486,8 +2495,8 @@ impl Arg {
     ///
     /// Setting `hide_long_help(true)` will hide the argument when displaying long help text
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2497,6 +2506,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays
@@ -2513,8 +2523,8 @@ impl Arg {
     ///
     /// However, when -h is called
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, Arg};
     /// let m = Command::new("prog")
     ///     .arg(Arg::new("cfg")
@@ -2524,6 +2534,7 @@ impl Arg {
     ///     .get_matches_from(vec![
     ///         "prog", "-h"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// Then the following would be displayed

diff --git a/src/builder/command.rs b/src/builder/command.rs
@@ -2608,8 +2608,8 @@ impl Command {
     ///
     /// # Examples
     ///
-    #[cfg_attr(not(feature = "help"), doc = " ```ignore")]
-    #[cfg_attr(feature = "help", doc = " ```")]
+    /// ```rust
+    /// # #[cfg(feature = "help")] {
     /// # use clap::{Command, };
     /// let m = Command::new("cust-ord")
     ///     .subcommand(Command::new("alpha") // typically subcommands are grouped
@@ -2627,6 +2627,7 @@ impl Command {
     ///     .get_matches_from(vec![
     ///         "cust-ord", "--help"
     ///     ]);
+    /// # }
     /// ```
     ///
     /// The above example displays the following help message
@@ -2756,8 +2757,8 @@ impl Command {
     ///
     /// # Examples
     ///
-    #[cfg_attr(not(unix), doc = " ```ignore")]
-    #[cfg_attr(unix, doc = " ```")]
+    /// ```rust
+    /// # #[cfg(unix)] {
     /// # use std::ffi::OsString;
     /// # use clap::Command;
     /// # use clap::value_parser;
@@ -2778,6 +2779,7 @@ impl Command {
     ///     },
     ///     _ => {},
     /// }
+    /// # }
     /// ```
     ///
     /// ```

diff --git a/src/builder/value_parser.rs b/src/builder/value_parser.rs
@@ -166,8 +166,8 @@ impl ValueParser {
     ///
     /// # Example
     ///
-    #[cfg_attr(not(unix), doc = " ```ignore")]
-    #[cfg_attr(unix, doc = " ```rust")]
+    /// ```rust
+    /// # #[cfg(unix)] {
     /// # use clap::{Command, Arg, builder::ValueParser};
     /// use std::ffi::OsString;
     /// use std::os::unix::ffi::{OsStrExt,OsStringExt};
@@ -187,6 +187,7 @@ impl ValueParser {
     /// let arg: &OsString = m.get_one("arg")
     ///     .expect("required");
     /// assert_eq!(arg.as_bytes(), &[0xe9]);
+    /// # }
     /// ```
     pub const fn os_string() -> Self {
         Self(ValueParserInner::OsString)
@@ -644,8 +645,8 @@ where
 ///
 /// # Example
 ///
-#[cfg_attr(not(feature = "error-context"), doc = " ```ignore")]
-#[cfg_attr(feature = "error-context", doc = " ```")]
+/// ```rust
+/// # #[cfg(feature = "error-context")] {
 /// # use clap::error::ErrorKind;
 /// # use clap::error::ContextKind;
 /// # use clap::error::ContextValue;
@@ -681,6 +682,7 @@ where
 ///         Ok(Custom(val))
 ///     }
 /// }
+/// # }
 /// ```
 pub trait TypedValueParser: Clone + Send + Sync + 'static {
     /// Argument's value type