Help us with better command and parameter/flag descriptions #5066
Comments
fdncred
added
help wanted
|
As a minor suggestion: all descriptions should follow the same grammar rule. E.g. |
|
@hyiltiz consistency would be a nice add. |
|
@fdncred I was looking into the outputs of some help commands. And I noticed that sometimes the explanation of a command (aka
Same thing applies for Also, there is an inconsistency with the arguments' description of some commands (below the command http get), some descriptions begin by a capital, where others don't:
I compared those outputs with ones from
So, I would recommend the following things:
Now, the last remaining thing: should we apply the same rules to the description of the examples? Should we begin those descriptions by a capital and prevent the ending with a dot? I'm completely opened to any suggestion here, and I would be happy to work on this uniformization. But, how could we prevent those deviations in the future? To prevent to do the same work multiples times in the future, and to reduce the PR review cumbersome on this part. |
|
@jaudiger Agreed. Some consistency would be nice. I think the example descriptions should have some uniformity too. |
|
with my new interest in is there some work being done here? |
|
@amtoine I just opened an MR to begin to work on the first two bullets points cited in my last comment. As for now, I just update the messages to make sure they all end with the same terminal character. |
…er. (#8268) # Description Working on uniformizing the ending messages regarding methods usage() and extra_usage(). This is related to the issue #5066 after discussing it with @jntrnr # User-Facing Changes None. # 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.
nice, that's cool thanks for the pointer 😋 |
|
@fdncred - we may want to turn this into a list of commands that need better help text so people can find where to jump in a bit more easily. |
|
@jntrnr maybe once we have a 1.0 list of commands. even still, having a list of every command and all their parameters may be unwieldy. |
|
i think help messages should all be aligned. It makes its more presentable and easier on the eyes. From jaudiger's comment above (#5066 (comment)) the help message in wget looks much much better than the ones from nu's help messages. |
Add a test to ensure that commands won't regress Part of nushell#5066 See also nushell#8268
Add a test to ensure that commands won't regress Part of nushell#5066 See also nushell#8268
# Description This repeats #8268 to make all command usage strings start with an uppercase letter and end with a period per #5056 Adds a test to ensure that commands won't regress Part of #5066 # User-Facing Changes Command usage is now consistent # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib` # After Submitting Automatic documentation updates
|
#11285 adds enforcement of positional arguments starting with an uppercase character and ending with a period. While making the tests pass I noticed that most commands have positional argument descriptions that are minimally descriptive like "The thing that does stuff" a smaller amount have "Thing that does the stuff" while a few have single-word descriptions for like "Thing". A good example of the difference is .required("def_name", SyntaxShape::String, "Command name.")
.required("params", SyntaxShape::Signature, "Parameters.")
.required("block", SyntaxShape::Block, "Body of the definition.")Single-word definitions that repeat the argument name aren't very helpful. For consistency these should be slightly more wordy like:
But maybe omitting "The"/"A"/"An" before providing a description for the argument is OK? |
|
@drbrain maybe we could explain a bit more?
|
OK Once the next release goes out and #11285 is merged I'll make another pass. |
…1278) # Description This repeats nushell#8268 to make all command usage strings start with an uppercase letter and end with a period per nushell#5056 Adds a test to ensure that commands won't regress Part of nushell#5066 # User-Facing Changes Command usage is now consistent # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib` # After Submitting Automatic documentation updates
…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
…1278) # Description This repeats nushell#8268 to make all command usage strings start with an uppercase letter and end with a period per nushell#5056 Adds a test to ensure that commands won't regress Part of nushell#5066 # User-Facing Changes Command usage is now consistent # Tests + Formatting - 🟢 `toolkit fmt` - 🟢 `toolkit clippy` - 🟢 `toolkit test` - 🟢 `toolkit test stdlib` # After Submitting Automatic documentation updates
…an uppercase and end with a period. (nushell#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 nushell#5066, specifically [this comment](/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 nushell#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
Hello! This is my first PR to nushell, as I was looking at things for #5066. The usage text for the date commands seemed fine to me, so this is just a bit of a tidy up of the examples, mostly the description text. # Description - Remove two incorrect examples for `date to-record` and `date to-table` where nothing was piped in (which causes an error in actual use). - Fix misleading descriptions in `date to-timezone` which erroneously referred to Hawaii's time zone. - Standardise on "time zone" in written descriptions. - Generally tidy up example descriptions and improve consistency. # User-Facing Changes Only in related help text showing examples.
Related problem
Some of our descriptions of commands and parameter descriptions could be more informative. Now that we've added descriptions in our completions, it would be nice to have them be as informative as possible without being too verbose.
Example of command descriptions
Example of parameter/flag descriptions
Describe the solution you'd like
We'd like to have helpful, concise descriptions for parameters/flags, and commands.
Describe alternatives you've considered
No response
Additional context and details
No response
The text was updated successfully, but these errors were encountered: