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](/nushell/nushell/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-command/tests/main.rs

@@ -1,6 +1,6 @@
 use nu_protocol::{
     engine::{EngineState, StateWorkingSet},
-    Category, Span,
+    Category, PositionalArg, Span,
 };
 use quickcheck_macros::quickcheck;
 
@@ -28,6 +28,92 @@ fn quickcheck_parse(data: String) -> bool {
     true
 }
 
+#[test]
+fn arguments_end_period() {
+    fn ends_period(cmd_name: &str, ty: &str, arg: PositionalArg, failures: &mut Vec<String>) {
+        let arg_name = arg.name;
+        let desc = arg.desc;
+        if !desc.ends_with('.') {
+            failures.push(format!(
+                "{cmd_name} {ty} argument \"{arg_name}\": \"{desc}\""
+            ));
+        }
+    }
+
+    let ctx = crate::create_default_context();
+    let decls = ctx.get_decls_sorted(true);
+    let mut failures = Vec::new();
+
+    for (name_bytes, decl_id) in decls {
+        let cmd = ctx.get_decl(decl_id);
+        let cmd_name = String::from_utf8_lossy(&name_bytes);
+        let signature = cmd.signature();
+
+        for arg in signature.required_positional {
+            ends_period(&cmd_name, "required", arg, &mut failures);
+        }
+
+        for arg in signature.optional_positional {
+            ends_period(&cmd_name, "optional", arg, &mut failures);
+        }
+
+        if let Some(arg) = signature.rest_positional {
+            ends_period(&cmd_name, "rest", arg, &mut failures);
+        }
+    }
+
+    assert!(
+        failures.is_empty(),
+        "Command argument description does not end with a period:\n{}",
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn arguments_start_uppercase() {
+    fn starts_uppercase(cmd_name: &str, ty: &str, arg: PositionalArg, failures: &mut Vec<String>) {
+        let arg_name = arg.name;
+        let desc = arg.desc;
+
+        // Check lowercase to allow usage to contain syntax like:
+        //
+        // "`as` keyword …"
+        if desc.starts_with(|u: char| u.is_lowercase()) {
+            failures.push(format!(
+                "{cmd_name} {ty} argument \"{arg_name}\": \"{desc}\""
+            ));
+        }
+    }
+
+    let ctx = crate::create_default_context();
+    let decls = ctx.get_decls_sorted(true);
+    let mut failures = Vec::new();
+
+    for (name_bytes, decl_id) in decls {
+        let cmd = ctx.get_decl(decl_id);
+        let cmd_name = String::from_utf8_lossy(&name_bytes);
+        let signature = cmd.signature();
+
+        for arg in signature.required_positional {
+            starts_uppercase(&cmd_name, "required", arg, &mut failures);
+        }
+
+        for arg in signature.optional_positional {
+            starts_uppercase(&cmd_name, "optional", arg, &mut failures);
+        }
+
+        if let Some(arg) = signature.rest_positional {
+            starts_uppercase(&cmd_name, "rest", arg, &mut failures);
+        }
+    }
+
+    assert!(
+        failures.is_empty(),
+        "Command argument description does not end with a period:\n{}",
+        failures.join("\n")
+    );
+}
+
 #[test]
 fn signature_name_matches_command_name() {
     let ctx = create_default_context();
@@ -145,7 +231,7 @@ fn usage_start_uppercase() {
         let cmd_name = String::from_utf8_lossy(&name_bytes);
         let usage = cmd.usage();
 
-        // Check lowercase to allow usage to contain removed syntax like:
+        // Check lowercase to allow usage to contain syntax like:
         //
         // "`let-env FOO = ...` …"
         if usage.starts_with(|u: char| u.is_lowercase()) {