Fix command descriptions+examples (#5129)

* Fix exit usage

* Move dfr as-date* format examples to extra_usage

* Update command usage and examples

* More docs on `str trim`

Co-authored-by: sholderbach <sholderbach@users.noreply.github.com>

crates/nu-command/src/conversions/fmt.rs

@@ -14,7 +14,7 @@ impl Command for Fmt {
     }
 
     fn usage(&self) -> &str {
-        "format numbers"
+        "Format a number"
     }
 
     fn signature(&self) -> nu_protocol::Signature {
@@ -23,7 +23,7 @@ impl Command for Fmt {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "format numbers",
+            description: "Get a record containing multiple formats for the number 42",
             example: "42 | fmt",
             result: Some(Value::Record {
                 cols: vec![

crates/nu-command/src/conversions/into/command.rs

@@ -18,7 +18,7 @@ impl Command for Into {
     }
 
     fn usage(&self) -> &str {
-        "Apply into function."
+        "Commands to convert data from one type to another."
     }
 
     fn run(

crates/nu-command/src/conversions/into/datetime.rs

@@ -101,7 +101,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts text into datetime"
+        "Convert text into a datetime"
     }
 
     fn examples(&self) -> Vec<Example> {

crates/nu-command/src/conversions/into/decimal.rs

@@ -22,7 +22,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts text into decimal"
+        "Convert text into a decimal"
     }
 
     fn run(

crates/nu-command/src/dataframe/eager/rename.rs

@@ -16,7 +16,7 @@ impl Command for RenameDF {
     }
 
     fn usage(&self) -> &str {
-        "rename a dataframe column"
+        "Rename a dataframe column"
     }
 
     fn signature(&self) -> Signature {

crates/nu-command/src/dataframe/series/date/as_date.rs

@@ -17,7 +17,11 @@ impl Command for AsDate {
     }
 
     fn usage(&self) -> &str {
-        r#"Converts string to date. Format example: 
+        r#"Converts string to date."#
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"Format example:
         "%Y-%m-%d"    => 2021-12-31
         "%d-%m-%Y"    => 31-12-2021
         "%Y%m%d"      => 2021319 (2021-03-19)"#
@@ -25,7 +29,7 @@ impl Command for AsDate {
 
     fn signature(&self) -> Signature {
         Signature::build(self.name())
-            .required("format", SyntaxShape::String, "formating date string")
+            .required("format", SyntaxShape::String, "formatting date string")
             .switch("not-exact", "the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)", Some('n'))
             .category(Category::Custom("dataframe".into()))
     }

crates/nu-command/src/dataframe/series/date/as_datetime.rs

@@ -18,7 +18,11 @@ impl Command for AsDateTime {
     }
 
     fn usage(&self) -> &str {
-        r#"Converts string to datetime. Format example: 
+        r#"Converts string to datetime."#
+    }
+
+    fn extra_usage(&self) -> &str {
+        r#"Format example:
         "%y/%m/%d %H:%M:%S"  => 21/12/31 12:54:98
         "%y-%m-%d %H:%M:%S"  => 2021-12-31 24:58:01
         "%y/%m/%d %H:%M:%S"  => 21/12/31 24:58:01
@@ -34,7 +38,7 @@ impl Command for AsDateTime {
 
     fn signature(&self) -> Signature {
         Signature::build(self.name())
-            .required("format", SyntaxShape::String, "formating date time string")
+            .required("format", SyntaxShape::String, "formatting date time string")
             .switch("not-exact", "the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)", Some('n'))
             .category(Category::Custom("dataframe".into()))
     }

crates/nu-command/src/date/date_.rs

@@ -18,7 +18,7 @@ impl Command for Date {
     }
 
     fn usage(&self) -> &str {
-        "date"
+        "Date-related commands"
     }
 
     fn run(

crates/nu-command/src/generators/seq_date.rs

@@ -17,7 +17,7 @@ impl Command for SeqDate {
     }
 
     fn usage(&self) -> &str {
-        "print sequences of dates"
+        "Print sequences of dates"
     }
 
     fn signature(&self) -> nu_protocol::Signature {

crates/nu-command/src/hash/generic_digest.rs

@@ -20,7 +20,7 @@ impl<D: HashDigest> Default for GenericDigest<D> {
     fn default() -> Self {
         Self {
             name: format!("hash {}", D::name()),
-            usage: format!("hash a value using the {} hash algorithm", D::name()),
+            usage: format!("Hash a value using the {} hash algorithm", D::name()),
             phantom: PhantomData,
         }
     }

crates/nu-command/src/network/url/host.rs

@@ -22,7 +22,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "gets the host of a url"
+        "Get the host of a URL"
     }
 
     fn run(

crates/nu-command/src/network/url/path.rs

@@ -22,7 +22,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "gets the path of a url"
+        "Get the path of a URL"
     }
 
     fn run(

crates/nu-command/src/network/url/query.rs

@@ -22,7 +22,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "gets the query of a url"
+        "Get the query string of a URL"
     }
 
     fn run(
@@ -39,7 +39,7 @@ impl Command for SubCommand {
         let span = Span::test_data();
         vec![
             Example {
-                description: "Get query of a url",
+                description: "Get a query string",
                 example: "echo 'http://www.example.com/?foo=bar&baz=quux' | url query",
                 result: Some(Value::String {
                     val: "foo=bar&baz=quux".to_string(),
@@ -47,7 +47,7 @@ impl Command for SubCommand {
                 }),
             },
             Example {
-                description: "No query gives the empty string",
+                description: "Returns an empty string if there is no query string",
                 example: "echo 'http://www.example.com/' | url query",
                 result: Some(Value::String {
                     val: "".to_string(),

crates/nu-command/src/network/url/scheme.rs

@@ -22,7 +22,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "gets the scheme (eg http, file) of a url"
+        "Get the scheme (e.g. http, file) of a URL"
     }
 
     fn run(
@@ -39,7 +39,7 @@ impl Command for SubCommand {
         let span = Span::test_data();
         vec![
             Example {
-                description: "Get scheme of a url",
+                description: "Get the scheme of a URL",
                 example: "echo 'http://www.example.com' | url scheme",
                 result: Some(Value::String {
                     val: "http".to_string(),

crates/nu-command/src/platform/ansi/gradient.rs

@@ -47,7 +47,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "draw text with a provided start and end code making a gradient"
+        "Draw text with a provided start and end code making a gradient"
     }
 
     fn run(

crates/nu-command/src/platform/ansi/strip.rs

@@ -18,13 +18,13 @@ impl Command for SubCommand {
             .rest(
                 "column path",
                 SyntaxShape::CellPath,
-                "optionally, remove ansi sequences by column paths",
+                "optionally, remove ANSI sequences by column paths",
             )
             .category(Category::Platform)
     }
 
     fn usage(&self) -> &str {
-        "strip ansi escape sequences from string"
+        "Strip ANSI escape sequences from a string"
     }
 
     fn run(
@@ -39,7 +39,7 @@ impl Command for SubCommand {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "strip ansi escape sequences from string",
+            description: "Strip ANSI escape sequences from a string",
             example: r#"echo [ (ansi green) (ansi cursor_on) "hello" ] | str collect | ansi strip"#,
             result: Some(Value::test_string("hello")),
         }]

crates/nu-command/src/shells/exit.rs

@@ -3,7 +3,6 @@ use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, SyntaxShape, Value};
 
-/// Source a file for environment variables.
 #[derive(Clone)]
 pub struct Exit;
 
@@ -19,12 +18,16 @@ impl Command for Exit {
                 SyntaxShape::Int,
                 "Exit code to return immediately with",
             )
-            .switch("now", "Exit out of the shell immediately", Some('n'))
+            .switch(
+                "now",
+                "Exit out of all shells immediately (exiting Nu)",
+                Some('n'),
+            )
             .category(Category::Shells)
     }
 
     fn usage(&self) -> &str {
-        "Runs a script file in the current context."
+        "Exit a Nu shell or exit Nu entirely."
     }
 
     fn run(

crates/nu-command/src/strings/detect_columns.rs

@@ -32,7 +32,7 @@ impl Command for DetectColumns {
     }
 
     fn usage(&self) -> &str {
-        "splits contents across multiple columns via the separator."
+        "Attempt to automatically split text into multiple columns"
     }
 
     fn run(

crates/nu-command/src/strings/split/chars.rs

@@ -17,7 +17,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "splits a string's characters into separate rows"
+        "Split a string's characters into separate rows"
     }
 
     fn examples(&self) -> Vec<Example> {

crates/nu-command/src/strings/split/column.rs

@@ -18,7 +18,7 @@ impl Command for SubCommand {
             .required(
                 "separator",
                 SyntaxShape::String,
-                "the character that denotes what separates columns",
+                "the character or string that denotes what separates columns",
             )
             .switch("collapse-empty", "remove empty columns", Some('c'))
             .rest(
@@ -30,7 +30,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "splits contents across multiple columns via the separator."
+        "Split a string into multiple columns using a separator"
     }
 
     fn run(

crates/nu-command/src/strings/split/row.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "splits contents over multiple rows via the separator."
+        "Split a string into multiple rows using a separator"
     }
 
     fn run(

crates/nu-command/src/strings/str_/capitalize.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "capitalizes text"
+        "Capitalize text"
     }
 
     fn run(

crates/nu-command/src/strings/str_/case/camel_case.rs

@@ -26,7 +26,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts a string to camelCase"
+        "Convert a string to camelCase"
     }
 
     fn run(

crates/nu-command/src/strings/str_/case/kebab_case.rs

@@ -26,7 +26,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts a string to kebab-case"
+        "Convert a string to kebab-case"
     }
 
     fn run(

crates/nu-command/src/strings/str_/case/pascal_case.rs

@@ -26,7 +26,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts a string to PascalCase"
+        "Convert a string to PascalCase"
     }
 
     fn run(

crates/nu-command/src/strings/str_/case/screaming_snake_case.rs

@@ -25,7 +25,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "converts a string to SCREAMING_SNAKE_CASE"
+        "Convert a string to SCREAMING_SNAKE_CASE"
     }
 
     fn run(

crates/nu-command/src/strings/str_/case/snake_case.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
             .category(Category::Strings)
     }
     fn usage(&self) -> &str {
-        "converts a string to snake_case"
+        "Convert a string to snake_case"
     }
 
     fn run(

crates/nu-command/src/strings/str_/collect.rs

@@ -25,7 +25,11 @@ impl Command for StrCollect {
     }
 
     fn usage(&self) -> &str {
-        "creates a string from the input, optionally using a separator"
+        "Concatenate multiple strings into a single string, with an optional separator between each"
+    }
+
+    fn search_terms(&self) -> Vec<&str> {
+        vec!["join", "concatenate"]
     }
 
     fn run(

crates/nu-command/src/strings/str_/downcase.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "downcases text"
+        "Make text lowercase"
     }
 
     fn search_terms(&self) -> Vec<&str> {

crates/nu-command/src/strings/str_/ends_with.rs

@@ -26,7 +26,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "checks if string ends with pattern"
+        "Check if a string ends with a pattern"
     }
 
     fn run(

crates/nu-command/src/strings/str_/length.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "outputs the lengths of the strings in the pipeline"
+        "Output the length of any strings in the pipeline"
     }
 
     fn run(

crates/nu-command/src/strings/str_/lpad.rs

@@ -38,7 +38,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "pad a string with a character a certain length"
+        "Left-pad a string to a specific length"
     }
 
     fn run(
@@ -54,7 +54,7 @@ impl Command for SubCommand {
     fn examples(&self) -> Vec<Example> {
         vec![
             Example {
-                description: "Left pad a string with a character a number of places",
+                description: "Left-pad a string with asterisks until it's 10 characters wide",
                 example: "'nushell' | str lpad -l 10 -c '*'",
                 result: Some(Value::String {
                     val: "***nushell".to_string(),
@@ -62,7 +62,7 @@ impl Command for SubCommand {
                 }),
             },
             Example {
-                description: "Left pad a string with a character a number of places",
+                description: "Left-pad a string with zeroes until it's 10 character wide",
                 example: "'123' | str lpad -l 10 -c '0'",
                 result: Some(Value::String {
                     val: "0000000123".to_string(),

crates/nu-command/src/strings/str_/replace.rs

@@ -42,7 +42,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "finds and replaces text"
+        "Find and replace text"
     }
 
     fn run(

crates/nu-command/src/strings/str_/reverse.rs

@@ -24,7 +24,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "outputs the reversals of the strings in the pipeline"
+        "Reverse every string in the pipeline"
     }
 
     fn run(
@@ -38,14 +38,37 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
+        vec![
-            description: "Return the reversals of multiple strings",
+            Example {
+                description: "Reverse a single string",
                 example: "'Nushell' | str reverse",
                 result: Some(Value::String {
                     val: "llehsuN".to_string(),
                     span: Span::test_data(),
                 }),
-        }]
+            },
+            Example {
+                description: "Reverse multiple strings in a list",
+                example: "['Nushell' 'is' 'cool'] | str reverse",
+                result: Some(Value::List {
+                    vals: vec![
+                        Value::String {
+                            val: "llehsuN".to_string(),
+                            span: Span::test_data(),
+                        },
+                        Value::String {
+                            val: "si".to_string(),
+                            span: Span::test_data(),
+                        },
+                        Value::String {
+                            val: "looc".to_string(),
+                            span: Span::test_data(),
+                        },
+                    ],
+                    span: Span::test_data(),
+                }),
+            },
+        ]
     }
 }
 

crates/nu-command/src/strings/str_/rpad.rs

@@ -38,7 +38,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "pad a string with a character a certain length"
+        "Right-pad a string to a specific length"
     }
 
     fn run(
@@ -54,7 +54,7 @@ impl Command for SubCommand {
     fn examples(&self) -> Vec<Example> {
         vec![
             Example {
-                description: "Right pad a string with a character a number of places",
+                description: "Right-pad a string with asterisks until it's 10 characters wide",
                 example: "'nushell' | str rpad -l 10 -c '*'",
                 result: Some(Value::String {
                     val: "nushell***".to_string(),
@@ -62,7 +62,7 @@ impl Command for SubCommand {
                 }),
             },
             Example {
-                description: "Right pad a string with a character a number of places",
+                description: "Right-pad a string with zeroes until it's 10 characters wide",
                 example: "'123' | str rpad -l 10 -c '0'",
                 result: Some(Value::String {
                     val: "1230000000".to_string(),

crates/nu-command/src/strings/str_/starts_with.rs

@@ -33,7 +33,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "checks if string starts with pattern"
+        "Check if string starts with a pattern"
     }
 
     fn run(

crates/nu-command/src/strings/str_/substring.rs

@@ -45,7 +45,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "substrings text"
+        "Get part of a string"
     }
 
     fn run(

crates/nu-command/src/strings/str_/trim/trim_.rs

@@ -59,7 +59,11 @@ impl Command for SubCommand {
             .switch("format", "trims spaces replacing multiple characters with singles in the middle (default: whitespace)", Some('f'))
     }
     fn usage(&self) -> &str {
-        "trims text"
+        "Trim whitespace or specific character"
+    }
+
+    fn search_terms(&self) -> Vec<&str> {
+        vec!["whitespace", "strip", "lstrip", "rstrip"]
     }
 
     fn run(

crates/nu-command/src/strings/str_/upcase.rs

@@ -21,7 +21,7 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "upcases text"
+        "Make text uppercase"
     }
 
     fn search_terms(&self) -> Vec<&str> {