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

@ -9,14 +9,14 @@ fn test_signature() {
assert_eq!(signature, from_build);
// constructing signature with description
let signature = Signature::new("signature").usage("example usage");
assert_eq!(signature.usage, "example usage".to_string())
let signature = Signature::new("signature").description("example description");
assert_eq!(signature.description, "example description".to_string())
}
#[test]
fn test_signature_chained() {
let signature = Signature::new("new_signature")
.usage("description")
.description("description")
.required("required", SyntaxShape::String, "required description")
.optional("optional", SyntaxShape::String, "optional description")
.required_named(
@ -126,7 +126,7 @@ fn test_signature_same_name() {
#[test]
fn test_signature_round_trip() {
let signature = Signature::new("new_signature")
.usage("description")
.description("description")
.required("first", SyntaxShape::String, "first required")
.required("second", SyntaxShape::Int, "second required")
.optional("optional", SyntaxShape::String, "optional description")
@ -145,8 +145,8 @@ fn test_signature_round_trip() {
let returned: Signature = serde_json::from_str(&string).unwrap();
assert_eq!(signature.name, returned.name);
assert_eq!(signature.usage, returned.usage);
assert_eq!(signature.extra_usage, returned.extra_usage);
assert_eq!(signature.description, returned.description);
assert_eq!(signature.extra_description, returned.extra_description);
assert_eq!(signature.is_filter, returned.is_filter);
assert_eq!(signature.category, returned.category);