Enforce required, optional, and rest positional arguments start with …

…an uppercase and end with a period. (#11285)

# Description

This updates all the positional arguments (except with
`--features=dataframe` or `--features=extra`) to start with an uppercase
letter and end with a period.

Part of #5066, specifically [this
comment](//issues/5066#issuecomment-1421528910)

Some arguments had example data removed from them because it also
appears in the examples.

There are other inconsistencies in positional arguments I noticed while
making the tests pass which I will bring up in #5066.

# User-Facing Changes

Positional arguments are now consistent

# Tests + Formatting

- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting

Automatic documentation updates

crates/nu-cmd-lang/src/core_commands/alias.rs

@@ -19,11 +19,11 @@ impl Command for Alias {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("alias")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("name", SyntaxShape::String, "name of the alias")
+            .required("name", SyntaxShape::String, "Name of the alias.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::Expression)),
-                "equals sign followed by value",
+                "Equals sign followed by value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/collect.rs

@@ -20,7 +20,7 @@ impl Command for Collect {
             .required(
                 "closure",
                 SyntaxShape::Closure(Some(vec![SyntaxShape::Any])),
-                "the closure to run once the stream is collected",
+                "The closure to run once the stream is collected.",
             )
             .switch(
                 "keep-env",

crates/nu-cmd-lang/src/core_commands/const_.rs

@@ -18,11 +18,11 @@ impl Command for Const {
         Signature::build("const")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("const_name", SyntaxShape::VarWithOptType, "constant name")
+            .required("const_name", SyntaxShape::VarWithOptType, "Constant name.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by constant value",
+                "Equals sign followed by constant value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/def.rs

@@ -19,9 +19,9 @@ impl Command for Def {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("def")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("def_name", SyntaxShape::String, "command name")
-            .required("params", SyntaxShape::Signature, "parameters")
-            .required("block", SyntaxShape::Closure(None), "body of the definition")
+            .required("def_name", SyntaxShape::String, "Command name.")
+            .required("params", SyntaxShape::Signature, "Parameters.")
+            .required("block", SyntaxShape::Closure(None), "Body of the definition.")
             .switch("env", "keep the environment defined inside the command", None)
             .switch("wrapped", "treat unknown flags and arguments as strings (requires ...rest-like parameter in signature)", None)
             .category(Category::Core)

crates/nu-cmd-lang/src/core_commands/do_.rs

@@ -25,7 +25,7 @@ impl Command for Do {
             .required(
                 "closure",
                 SyntaxShape::OneOf(vec![SyntaxShape::Closure(None), SyntaxShape::Any]),
-                "the closure to run",
+                "The closure to run.",
             )
             .input_output_types(vec![(Type::Any, Type::Any)])
             .switch(
@@ -53,7 +53,11 @@ impl Command for Do {
                 "keep the environment defined inside the command",
                 None,
             )
-            .rest("rest", SyntaxShape::Any, "the parameter(s) for the closure")
+            .rest(
+                "rest",
+                SyntaxShape::Any,
+                "The parameter(s) for the closure.",
+            )
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/echo.rs

@@ -21,7 +21,7 @@ impl Command for Echo {
     fn signature(&self) -> Signature {
         Signature::build("echo")
             .input_output_types(vec![(Type::Nothing, Type::Any)])
-            .rest("rest", SyntaxShape::Any, "the values to echo")
+            .rest("rest", SyntaxShape::Any, "The values to echo.")
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/error_make.rs

@@ -19,7 +19,7 @@ impl Command for ErrorMake {
             .required(
                 "error_struct",
                 SyntaxShape::Record(vec![]),
-                "the error to create",
+                "The error to create.",
             )
             .switch(
                 "unspanned",

crates/nu-cmd-lang/src/core_commands/export_alias.rs

@@ -19,11 +19,11 @@ impl Command for ExportAlias {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("export alias")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("name", SyntaxShape::String, "name of the alias")
+            .required("name", SyntaxShape::String, "Name of the alias.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::Expression)),
-                "equals sign followed by value",
+                "Equals sign followed by value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/export_const.rs

@@ -20,11 +20,11 @@ impl Command for ExportConst {
         Signature::build("export const")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("const_name", SyntaxShape::VarWithOptType, "constant name")
+            .required("const_name", SyntaxShape::VarWithOptType, "Constant name.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by constant value",
+                "Equals sign followed by constant value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/export_def.rs

@@ -19,9 +19,9 @@ impl Command for ExportDef {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("export def")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("def_name", SyntaxShape::String, "command name")
-            .required("params", SyntaxShape::Signature, "parameters")
-            .required("block", SyntaxShape::Block, "body of the definition")
+            .required("def_name", SyntaxShape::String, "Command name.")
+            .required("params", SyntaxShape::Signature, "Parameters.")
+            .required("block", SyntaxShape::Block, "Body of the definition.")
             .switch("env", "keep the environment defined inside the command", None)
             .switch("wrapped", "treat unknown flags and arguments as strings (requires ...rest-like parameter in signature)", None)
             .category(Category::Core)

crates/nu-cmd-lang/src/core_commands/export_extern.rs

@@ -17,8 +17,8 @@ impl Command for ExportExtern {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("export extern")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("def_name", SyntaxShape::String, "definition name")
-            .required("params", SyntaxShape::Signature, "parameters")
+            .required("def_name", SyntaxShape::String, "Definition name.")
+            .required("params", SyntaxShape::Signature, "Parameters.")
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/export_module.rs

@@ -20,11 +20,11 @@ impl Command for ExportModule {
         Signature::build("export module")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("module", SyntaxShape::String, "module name or module path")
+            .required("module", SyntaxShape::String, "Module name or module path.")
             .optional(
                 "block",
                 SyntaxShape::Block,
-                "body of the module if 'module' parameter is not a path",
+                "Body of the module if 'module' parameter is not a path.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/export_use.rs

@@ -19,11 +19,11 @@ impl Command for ExportUse {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("export use")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("module", SyntaxShape::String, "Module or module file")
+            .required("module", SyntaxShape::String, "Module or module file.")
             .optional(
                 "members",
                 SyntaxShape::Any,
-                "Which members of the module to import",
+                "Which members of the module to import.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/extern_.rs

@@ -17,8 +17,8 @@ impl Command for Extern {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("extern")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("def_name", SyntaxShape::String, "definition name")
-            .required("params", SyntaxShape::Signature, "parameters")
+            .required("def_name", SyntaxShape::String, "Definition name.")
+            .required("params", SyntaxShape::Signature, "Parameters.")
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/for_.rs

@@ -25,14 +25,14 @@ impl Command for For {
             .required(
                 "var_name",
                 SyntaxShape::VarWithOptType,
-                "name of the looping variable",
+                "Name of the looping variable.",
             )
             .required(
                 "range",
                 SyntaxShape::Keyword(b"in".to_vec(), Box::new(SyntaxShape::Any)),
-                "range of the loop",
+                "Range of the loop.",
             )
-            .required("block", SyntaxShape::Block, "the block to run")
+            .required("block", SyntaxShape::Block, "The block to run.")
             .switch(
                 "numbered",
                 "return a numbered item ($it.index and $it.item)",

crates/nu-cmd-lang/src/core_commands/hide.rs

@@ -13,11 +13,11 @@ impl Command for Hide {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("hide")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .required("module", SyntaxShape::String, "Module or module file")
+            .required("module", SyntaxShape::String, "Module or module file.")
             .optional(
                 "members",
                 SyntaxShape::Any,
-                "Which members of the module to import",
+                "Which members of the module to import.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/hide_env.rs

@@ -20,7 +20,7 @@ impl Command for HideEnv {
             .rest(
                 "name",
                 SyntaxShape::String,
-                "environment variable names to hide",
+                "Environment variable names to hide.",
             )
             .switch(
                 "ignore-errors",

crates/nu-cmd-lang/src/core_commands/if_.rs

@@ -21,11 +21,11 @@ impl Command for If {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("if")
             .input_output_types(vec![(Type::Any, Type::Any)])
-            .required("cond", SyntaxShape::MathExpression, "condition to check")
+            .required("cond", SyntaxShape::MathExpression, "Condition to check.")
             .required(
                 "then_block",
                 SyntaxShape::Block,
-                "block to run if check succeeds",
+                "Block to run if check succeeds.",
             )
             .optional(
                 "else_expression",
@@ -36,7 +36,7 @@ impl Command for If {
                         SyntaxShape::Expression,
                     ])),
                 ),
-                "expression or block to run if check fails",
+                "Expression or block to run when the condition is false.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/let_.rs

@@ -19,11 +19,11 @@ impl Command for Let {
         Signature::build("let")
             .input_output_types(vec![(Type::Any, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("var_name", SyntaxShape::VarWithOptType, "variable name")
+            .required("var_name", SyntaxShape::VarWithOptType, "Variable name.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by value",
+                "Equals sign followed by value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/loop_.rs

@@ -21,7 +21,7 @@ impl Command for Loop {
         Signature::build("loop")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("block", SyntaxShape::Block, "block to loop")
+            .required("block", SyntaxShape::Block, "Block to loop.")
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/match_.rs

@@ -20,11 +20,11 @@ impl Command for Match {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("match")
             .input_output_types(vec![(Type::Any, Type::Any)])
-            .required("value", SyntaxShape::Any, "value to check")
+            .required("value", SyntaxShape::Any, "Value to check.")
             .required(
                 "match_block",
                 SyntaxShape::MatchBlock,
-                "block to run if check succeeds",
+                "Block to run if check succeeds.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/module.rs

@@ -20,11 +20,11 @@ impl Command for Module {
         Signature::build("module")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("module", SyntaxShape::String, "module name or module path")
+            .required("module", SyntaxShape::String, "Module name or module path.")
             .optional(
                 "block",
                 SyntaxShape::Block,
-                "body of the module if 'module' parameter is not a module path",
+                "Body of the module if 'module' parameter is not a module path.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/mut_.rs

@@ -19,11 +19,11 @@ impl Command for Mut {
         Signature::build("mut")
             .input_output_types(vec![(Type::Any, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("var_name", SyntaxShape::VarWithOptType, "variable name")
+            .required("var_name", SyntaxShape::VarWithOptType, "Variable name.")
             .required(
                 "initial_value",
                 SyntaxShape::Keyword(b"=".to_vec(), Box::new(SyntaxShape::MathExpression)),
-                "equals sign followed by value",
+                "Equals sign followed by value.",
             )
             .category(Category::Core)
     }

crates/nu-cmd-lang/src/core_commands/overlay/hide.rs

@@ -20,10 +20,10 @@ impl Command for OverlayHide {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("overlay hide")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
-            .optional("name", SyntaxShape::String, "Overlay to hide")
+            .optional("name", SyntaxShape::String, "Overlay to hide.")
             .switch(
                 "keep-custom",
-                "Keep all newly added commands and aliases in the next activated overlay",
+                "Keep all newly added commands and aliases in the next activated overlay.",
                 Some('k'),
             )
             .named(

crates/nu-cmd-lang/src/core_commands/overlay/new.rs

@@ -21,7 +21,7 @@ impl Command for OverlayNew {
         Signature::build("overlay new")
             .input_output_types(vec![(Type::Nothing, Type::Nothing)])
             .allow_variants_without_examples(true)
-            .required("name", SyntaxShape::String, "Name of the overlay")
+            .required("name", SyntaxShape::String, "Name of the overlay.")
             // TODO:
             // .switch(
             //     "prefix",

crates/nu-cmd-lang/src/core_commands/overlay/use_.rs

@@ -27,12 +27,12 @@ impl Command for OverlayUse {
             .required(
                 "name",
                 SyntaxShape::String,
-                "Module name to use overlay for",
+                "Module name to use overlay for.",
             )
             .optional(
                 "as",
                 SyntaxShape::Keyword(b"as".to_vec(), Box::new(SyntaxShape::String)),
-                "as keyword followed by a new name",
+                "`as` keyword followed by a new name.",
             )
             .switch(
                 "prefix",

crates/nu-cmd-lang/src/core_commands/register.rs

@@ -20,12 +20,12 @@ impl Command for Register {
             .required(
                 "plugin",
                 SyntaxShape::Filepath,
-                "path of executable for plugin",
+                "Path of executable for plugin.",
             )
             .optional(
                 "signature",
                 SyntaxShape::Any,
-                "Block with signature description as json object",
+                "Block with signature description as json object.",
             )
             .named(
                 "shell",

crates/nu-cmd-lang/src/core_commands/return_.rs

@@ -20,7 +20,11 @@ impl Command for Return {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("return")
             .input_output_types(vec![(Type::Nothing, Type::Any)])
-            .optional("return_value", SyntaxShape::Any, "optional value to return")
+            .optional(
+                "return_value",
+                SyntaxShape::Any,
+                "Optional value to return.",
+            )
             .category(Category::Core)
     }
 

crates/nu-cmd-lang/src/core_commands/try_.rs

@@ -21,7 +21,7 @@ impl Command for Try {
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("try")
             .input_output_types(vec![(Type::Any, Type::Any)])
-            .required("try_block", SyntaxShape::Block, "block to run")
+            .required("try_block", SyntaxShape::Block, "Block to run.")
             .optional(
                 "catch_block",
                 SyntaxShape::Keyword(
@@ -31,7 +31,7 @@ impl Command for Try {
                         SyntaxShape::Closure(Some(vec![SyntaxShape::Any])),
                     ])),
                 ),
-                "block to run if try block fails",
+                "Block to run if try block fails.",
             )
             .category(Category::Core)
     }