Change the usage misnomer to "description" (#13598)

# Description
    
The meaning of the word usage is specific to describing how a command
function is *used* and not a synonym for general description. Usage can
be used to describe the SYNOPSIS or EXAMPLES sections of a man page
where the permitted argument combinations are shown or example *uses*
are given.
Let's not confuse people and call it what it is a description.

Our `help` command already creates its own *Usage* section based on the
available arguments and doesn't refer to the description with usage.

# User-Facing Changes

`help commands` and `scope commands` will now use `description` or
`extra_description`
`usage`-> `description`
`extra_usage` -> `extra_description`

Breaking change in the plugin protocol:

In the signature record communicated with the engine.
`usage`-> `description`
`extra_usage` -> `extra_description`

The same rename also takes place for the methods on
`SimplePluginCommand` and `PluginCommand`

# Tests + Formatting
- Updated plugin protocol specific changes
# After Submitting
- [ ] update plugin protocol doc
This commit is contained in:
Stefan Holderbach
2024-08-22 12:02:08 +02:00
committed by GitHub
parent 3ab9f0b90a
commit 95b78eee25
597 changed files with 1085 additions and 1039 deletions

View File

@ -14,11 +14,11 @@ impl Command for ConfigMeta {
.input_output_types(vec![(Type::Nothing, Type::String)])
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Edit nushell configuration files."
}
fn extra_usage(&self) -> &str {
fn extra_description(&self) -> &str {
"You must use one of the following subcommands. Using this command as-is will only produce this help message."
}

View File

@ -19,7 +19,7 @@ impl Command for ConfigEnv {
// TODO: Signature narrower than what run actually supports theoretically
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Edit nu environment configurations."
}

View File

@ -23,7 +23,7 @@ impl Command for ConfigNu {
// TODO: Signature narrower than what run actually supports theoretically
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Edit nu configurations."
}

View File

@ -22,7 +22,7 @@ impl Command for ConfigReset {
.category(Category::Env)
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Reset nushell environment configurations to default, and saves old config files in the config location as oldconfig.nu and oldenv.nu."
}

View File

@ -20,11 +20,11 @@ impl Command for ExportEnv {
.category(Category::Env)
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Run a block and preserve its environment in a current scope."
}
fn extra_usage(&self) -> &str {
fn extra_description(&self) -> &str {
r#"This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html"#
}

View File

@ -8,7 +8,7 @@ impl Command for LoadEnv {
"load-env"
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Loads an environment update from a record."
}

View File

@ -25,11 +25,11 @@ impl Command for SourceEnv {
.category(Category::Core)
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Source the environment from a source file into the current environment."
}
fn extra_usage(&self) -> &str {
fn extra_description(&self) -> &str {
r#"This command is a parser keyword. For details, check:
https://www.nushell.sh/book/thinking_in_nu.html"#
}

View File

@ -25,7 +25,7 @@ impl Command for WithEnv {
.category(Category::Env)
}
fn usage(&self) -> &str {
fn description(&self) -> &str {
"Runs a block with an environment variable set."
}