Enforce required, optional, and rest positional arguments start with an uppercase and end with a period.

[drbrain]

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

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

[fdncred]

wow, that's a lot of changes. thanks for all the hard work. i'm especially glad to enforce consistency with tests. i'm a little bit nervous on landing this one before our release tomorrow since it's so big.

[drbrain]

i'm a little bit nervous on landing this one before our release tomorrow since it's so big.

I'm in no rush to merge

[ghost]

Hi @drbrain 👋, where does one find the toolkit used for these updates?

[WindSoilder]

Thanks! I really love these two added tests: arguments_start_uppercase, arguments_end_period

[fdncred]

@drbrain I'm wondering if all parameters are checked for uppercase and period. I just landed a PR that passed the test but didn't have a period in the switches. https://github.com/nushell/nushell/pull/11324/files#diff-61e5ce298fd8925da5182d9bddcf1d27568c5a74ece04c9f9b8a699688ec5bbcR481-R484

[Deebster]

This change seems to have a few problems, and does not match with what was agreed in #5066:

Argument desc: begin by a capital and do not end with a dot

However, this PR enforces the opposite, and now parameters are inconsistent with flags, even though they're both arguments (in the argv sense).

Also, now the (optional) annotation looks like an error since it is lowercase but appears as a new sentence.

For example, in hide --help we see this:

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

Parameters:
  module <string>: Module or module file.
  members <any>: Which members of the module to import. (optional)

Instead of the cleaner and more consistent:

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

Parameters:
  module <string>: Module or module file
  members <any>: Which members of the module to import (optional)