Skip to content

Commit 80ec801

Browse files
mTsBucy1mTsBucy1
authored
task: clarify process::Command docs (#5406) (#5413)
1 parent 88b1eb5 commit 80ec801

1 file changed

Lines changed: 67 additions & 28 deletions

File tree

‎tokio/src/process/mod.rs‎

Lines changed: 67 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,8 @@ impl Command {
309309
///
310310
/// ```no_run
311311
/// use tokio::process::Command;
312-
/// let command = Command::new("sh");
312+
/// let mut command = Command::new("sh");
313+
/// # let _ = command.output(); // assert borrow checker
313314
/// ```
314315
///
315316
/// [rust-lang/rust#37519]: https://github.com/rust-lang/rust/issues/37519
@@ -328,16 +329,20 @@ impl Command {
328329
/// Only one argument can be passed per use. So instead of:
329330
///
330331
/// ```no_run
331-
/// tokio::process::Command::new("sh")
332-
/// .arg("-C /path/to/repo");
332+
/// let mut command = tokio::process::Command::new("sh");
333+
/// command.arg("-C /path/to/repo");
334+
///
335+
/// # let _ = command.output(); // assert borrow checker
333336
/// ```
334337
///
335338
/// usage would be:
336339
///
337340
/// ```no_run
338-
/// tokio::process::Command::new("sh")
339-
/// .arg("-C")
340-
/// .arg("/path/to/repo");
341+
/// let mut command = tokio::process::Command::new("sh");
342+
/// command.arg("-C");
343+
/// command.arg("/path/to/repo");
344+
///
345+
/// # let _ = command.output(); // assert borrow checker
341346
/// ```
342347
///
343348
/// To pass multiple arguments see [`args`].
@@ -349,11 +354,15 @@ impl Command {
349354
/// Basic usage:
350355
///
351356
/// ```no_run
357+
/// # async fn test() { // allow using await
352358
/// use tokio::process::Command;
353359
///
354-
/// let command = Command::new("ls")
360+
/// let output = Command::new("ls")
355361
/// .arg("-l")
356-
/// .arg("-a");
362+
/// .arg("-a")
363+
/// .output().await.unwrap();
364+
/// # }
365+
///
357366
/// ```
358367
pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command {
359368
self.std.arg(arg);
@@ -371,10 +380,13 @@ impl Command {
371380
/// Basic usage:
372381
///
373382
/// ```no_run
383+
/// # async fn test() { // allow using await
374384
/// use tokio::process::Command;
375385
///
376-
/// let command = Command::new("ls")
377-
/// .args(&["-l", "-a"]);
386+
/// let output = Command::new("ls")
387+
/// .args(&["-l", "-a"])
388+
/// .output().await.unwrap();
389+
/// # }
378390
/// ```
379391
pub fn args<I, S>(&mut self, args: I) -> &mut Command
380392
where
@@ -395,10 +407,13 @@ impl Command {
395407
/// Basic usage:
396408
///
397409
/// ```no_run
410+
/// # async fn test() { // allow using await
398411
/// use tokio::process::Command;
399412
///
400-
/// let command = Command::new("ls")
401-
/// .env("PATH", "/bin");
413+
/// let output = Command::new("ls")
414+
/// .env("PATH", "/bin")
415+
/// .output().await.unwrap();
416+
/// # }
402417
/// ```
403418
pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
404419
where
@@ -416,6 +431,7 @@ impl Command {
416431
/// Basic usage:
417432
///
418433
/// ```no_run
434+
/// # async fn test() { // allow using await
419435
/// use tokio::process::Command;
420436
/// use std::process::{Stdio};
421437
/// use std::env;
@@ -426,11 +442,13 @@ impl Command {
426442
/// k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
427443
/// ).collect();
428444
///
429-
/// let command = Command::new("printenv")
445+
/// let output = Command::new("printenv")
430446
/// .stdin(Stdio::null())
431447
/// .stdout(Stdio::inherit())
432448
/// .env_clear()
433-
/// .envs(&filtered_env);
449+
/// .envs(&filtered_env)
450+
/// .output().await.unwrap();
451+
/// # }
434452
/// ```
435453
pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
436454
where
@@ -449,10 +467,13 @@ impl Command {
449467
/// Basic usage:
450468
///
451469
/// ```no_run
470+
/// # async fn test() { // allow using await
452471
/// use tokio::process::Command;
453472
///
454-
/// let command = Command::new("ls")
455-
/// .env_remove("PATH");
473+
/// let output = Command::new("ls")
474+
/// .env_remove("PATH")
475+
/// .output().await.unwrap();
476+
/// # }
456477
/// ```
457478
pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Command {
458479
self.std.env_remove(key);
@@ -466,10 +487,13 @@ impl Command {
466487
/// Basic usage:
467488
///
468489
/// ```no_run
490+
/// # async fn test() { // allow using await
469491
/// use tokio::process::Command;
470492
///
471-
/// let command = Command::new("ls")
472-
/// .env_clear();
493+
/// let output = Command::new("ls")
494+
/// .env_clear()
495+
/// .output().await.unwrap();
496+
/// # }
473497
/// ```
474498
pub fn env_clear(&mut self) -> &mut Command {
475499
self.std.env_clear();
@@ -493,10 +517,13 @@ impl Command {
493517
/// Basic usage:
494518
///
495519
/// ```no_run
520+
/// # async fn test() { // allow using await
496521
/// use tokio::process::Command;
497522
///
498-
/// let command = Command::new("ls")
499-
/// .current_dir("/bin");
523+
/// let output = Command::new("ls")
524+
/// .current_dir("/bin")
525+
/// .output().await.unwrap();
526+
/// # }
500527
/// ```
501528
pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
502529
self.std.current_dir(dir);
@@ -516,11 +543,14 @@ impl Command {
516543
/// Basic usage:
517544
///
518545
/// ```no_run
546+
/// # async fn test() { // allow using await
519547
/// use std::process::{Stdio};
520548
/// use tokio::process::Command;
521549
///
522-
/// let command = Command::new("ls")
523-
/// .stdin(Stdio::null());
550+
/// let output = Command::new("ls")
551+
/// .stdin(Stdio::null())
552+
/// .output().await.unwrap();
553+
/// # }
524554
/// ```
525555
pub fn stdin<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
526556
self.std.stdin(cfg);
@@ -540,11 +570,14 @@ impl Command {
540570
/// Basic usage:
541571
///
542572
/// ```no_run
573+
/// # async fn test() { // allow using await
543574
/// use tokio::process::Command;
544575
/// use std::process::Stdio;
545576
///
546-
/// let command = Command::new("ls")
547-
/// .stdout(Stdio::null());
577+
/// let output = Command::new("ls")
578+
/// .stdout(Stdio::null())
579+
/// .output().await.unwrap();
580+
/// # }
548581
/// ```
549582
pub fn stdout<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
550583
self.std.stdout(cfg);
@@ -564,11 +597,14 @@ impl Command {
564597
/// Basic usage:
565598
///
566599
/// ```no_run
600+
/// # async fn test() { // allow using await
567601
/// use tokio::process::Command;
568602
/// use std::process::{Stdio};
569603
///
570-
/// let command = Command::new("ls")
571-
/// .stderr(Stdio::null());
604+
/// let output = Command::new("ls")
605+
/// .stderr(Stdio::null())
606+
/// .output().await.unwrap();
607+
/// # }
572608
/// ```
573609
pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command {
574610
self.std.stderr(cfg);
@@ -707,10 +743,13 @@ impl Command {
707743
/// [`tokio::process::Command`]: crate::process::Command
708744
///
709745
/// ```no_run
746+
/// # async fn test() { // allow using await
710747
/// use tokio::process::Command;
711748
///
712-
/// let command = Command::new("ls")
713-
/// .process_group(0);
749+
/// let output = Command::new("ls")
750+
/// .process_group(0)
751+
/// .output().await.unwrap();
752+
/// # }
714753
/// ```
715754
#[cfg(unix)]
716755
#[cfg(tokio_unstable)]

0 commit comments

Comments
 (0)