From 1d8775d237e22b71b632e98ef4b2304d58ac436e Mon Sep 17 00:00:00 2001
From: WindSoilder <WindSoilder@outlook.com>
Date: Sun, 29 Jan 2023 06:42:05 +0800
Subject: [PATCH] mention `do` in `complete` command's doc (#7884)

# Description

Closes: #7841

# User-Facing Changes

new complete doc:
```
Complete the external piped in, collecting outputs and exit code

To collect stderr messages and exit_code, external piped in need to wrapped with `do`

Usage:
  > complete

Flags:
  -h, --help - Display the help message for this command

Signatures:
  <any> | complete -> <record>

Examples:
  Run the external completion
  > ^external arg1 | complete

  Run external completion, collects stderr and exit_code
  > do { ^external arg1 } | complete
```

# Tests + Formatting

Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A
clippy::needless_collect` to check that you're using the standard code
style
- `cargo test --workspace` to check that all tests pass

# After Submitting

If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.

---------

Co-authored-by: Darren Schroeder <343840+fdncred@users.noreply.github.com>
---
 crates/nu-command/src/system/complete.rs | 25 ++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/crates/nu-command/src/system/complete.rs b/crates/nu-command/src/system/complete.rs
index 4a925f5199..a78b69bf53 100644
--- a/crates/nu-command/src/system/complete.rs
+++ b/crates/nu-command/src/system/complete.rs
@@ -21,7 +21,11 @@ impl Command for Complete {
     }
 
     fn usage(&self) -> &str {
-        "Complete the external piped in, collecting outputs and exit code"
+        "Capture the outputs and exit code from an external piped in command in a nushell table"
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"In order to capture stdout, stderr, and exit_code, externally piped in commands need to be wrapped with `do`"#
     }
 
     fn run(
@@ -128,10 +132,19 @@ impl Command for Complete {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            description: "Run the external completion",
-            example: "^external arg1 | complete",
-            result: None,
-        }]
+        vec![
+            Example {
+                description:
+                    "Run the external command to completion, capturing stdout and exit_code",
+                example: "^external arg1 | complete",
+                result: None,
+            },
+            Example {
+                description:
+                    "Run external command to completion, capturing, stdout, stderr and exit_code",
+                example: "do { ^external arg1 } | complete",
+                result: None,
+            },
+        ]
     }
 }