bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #126188 - Kobzol:runmake-command-docs, r=jieyouxu

Browse source 
Fix documentation for `impl_common_helpers` in `run-make-support`

Forgot to do this in https://github.com/rust-lang/rust/pull/126121.

`@bors` rollup

r? `@jieyouxu`
This commit is contained in:
许杰友 Jieyou Xu (Joe) 2024-06-09 19:16:21 +01:00 • committed by GitHub
commit a8cba36cbf
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 6 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

20
src/tools/run-make-support/src/lib.rs
View file

@ -318,38 +318,30 @@ pub fn run_in_tmpdir<F: FnOnce()>(callback: F) {
} }
/// Implement common helpers for command wrappers. This assumes that the command wrapper is a struct /// Implement common helpers for command wrappers. This assumes that the command wrapper is a struct
/// containing a `cmd: Command` field and a `output` function. The provided helpers are: /// containing a `cmd: Command` field. The provided helpers are:
/// ///
/// 1. Generic argument acceptors: `arg` and `args` (delegated to [`Command`]). These are intended /// 1. Generic argument acceptors: `arg` and `args` (delegated to [`Command`]). These are intended
/// to be *fallback* argument acceptors, when specific helpers don't make sense. Prefer to add /// to be *fallback* argument acceptors, when specific helpers don't make sense. Prefer to add
/// new specific helper methods over relying on these generic argument providers. /// new specific helper methods over relying on these generic argument providers.
/// 2. Environment manipulation methods: `env`, `env_remove` and `env_clear`: these delegate to /// 2. Environment manipulation methods: `env`, `env_remove` and `env_clear`: these delegate to
/// methods of the same name on [`Command`]. /// methods of the same name on [`Command`].
/// 3. Output and execution: `output`, `run` and `run_fail` are provided. `output` waits for the /// 3. Output and execution: `run` and `run_fail` are provided. These are
/// command to finish running and returns the process's [`Output`]. `run` and `run_fail` are /// higher-level convenience methods which wait for the command to finish running and assert
/// higher-level convenience methods which waits for the command to finish running and assert /// that the command successfully ran or failed as expected. They return
/// that the command successfully ran or failed as expected. Prefer `run` and `run_fail` when /// [`CompletedProcess`], which can be used to assert the stdout/stderr/exit code of the executed
/// possible. /// process.
/// ///
/// Example usage: /// Example usage:
/// ///
/// ```ignore (illustrative) /// ```ignore (illustrative)
/// struct CommandWrapper { cmd: Command } // <- required `cmd` field /// struct CommandWrapper { cmd: Command } // <- required `cmd` field
/// ///
/// impl CommandWrapper {
/// /// Get the [`Output`][::std::process::Output] of the finished process.
/// pub fn command_output(&mut self) -> Output { /* ... */ } // <- required `command_output()` method
/// }
///
/// crate::impl_common_helpers!(CommandWrapper); /// crate::impl_common_helpers!(CommandWrapper);
/// ///
/// impl CommandWrapper { /// impl CommandWrapper {
/// // ... additional specific helper methods /// // ... additional specific helper methods
/// } /// }
/// ``` /// ```
///
/// [`Command`]: ::std::process::Command
/// [`Output`]: ::std::process::Output
macro_rules! impl_common_helpers { macro_rules! impl_common_helpers {
($wrapper: ident) => { ($wrapper: ident) => {
impl $wrapper { impl $wrapper {