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

crates/nu-cmd-lang/src/core_commands/alias.rs

@@ -9,7 +9,7 @@ impl Command for Alias {
         "alias"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Alias a command (with optional flags) to a new name."
     }
 
@@ -25,7 +25,7 @@ impl Command for Alias {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/break_.rs

@@ -9,7 +9,7 @@ impl Command for Break {
         "break"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Break a loop."
     }
 
@@ -19,7 +19,7 @@ impl Command for Break {
             .category(Category::Core)
     }
 
-    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
 

crates/nu-cmd-lang/src/core_commands/collect.rs

@@ -25,11 +25,11 @@ impl Command for Collect {
             .category(Category::Filters)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Collect a stream into a value."
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         r#"If provided, run a closure with the collected value as input.
 
 The entire stream will be collected into one value in memory, so if the stream

crates/nu-cmd-lang/src/core_commands/const_.rs

@@ -9,7 +9,7 @@ impl Command for Const {
         "const"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create a parse-time constant."
     }
 
@@ -26,7 +26,7 @@ impl Command for Const {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/continue_.rs

@@ -9,7 +9,7 @@ impl Command for Continue {
         "continue"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Continue a loop from the next iteration."
     }
 
@@ -19,7 +19,7 @@ impl Command for Continue {
             .category(Category::Core)
     }
 
-    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
 

crates/nu-cmd-lang/src/core_commands/def.rs

@@ -9,7 +9,7 @@ impl Command for Def {
         "def"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Define a custom command."
     }
 
@@ -24,7 +24,7 @@ impl Command for Def {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/describe.rs

@@ -9,7 +9,7 @@ impl Command for Describe {
         "describe"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Describe the type and structure of the value(s) piped in."
     }
 

crates/nu-cmd-lang/src/core_commands/do_.rs

@@ -17,7 +17,7 @@ impl Command for Do {
         "do"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Run a closure, providing it with the pipeline input."
     }
 

crates/nu-cmd-lang/src/core_commands/echo.rs

@@ -8,7 +8,7 @@ impl Command for Echo {
         "echo"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Returns its arguments, ignoring the piped-in value."
     }
 
@@ -19,7 +19,7 @@ impl Command for Echo {
             .category(Category::Core)
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         r#"Unlike `print`, which prints unstructured text to stdout, `echo` is like an
 identity function and simply returns its arguments. When given no arguments,
 it returns an empty string. When given one argument, it returns it as a

crates/nu-cmd-lang/src/core_commands/error_make.rs

@@ -25,7 +25,7 @@ impl Command for ErrorMake {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create an error."
     }
 

crates/nu-cmd-lang/src/core_commands/export.rs

@@ -15,11 +15,11 @@ impl Command for ExportCommand {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Export definitions or environment variables from a module."
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_alias.rs

@@ -9,7 +9,7 @@ impl Command for ExportAlias {
         "export alias"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Alias a command (with optional flags) to a new name and export it from a module."
     }
 
@@ -25,7 +25,7 @@ impl Command for ExportAlias {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_const.rs

@@ -9,7 +9,7 @@ impl Command for ExportConst {
         "export const"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Use parse-time constant from a module and export them from this module."
     }
 
@@ -26,7 +26,7 @@ impl Command for ExportConst {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_def.rs

@@ -9,7 +9,7 @@ impl Command for ExportDef {
         "export def"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Define a custom command and export it from a module."
     }
 
@@ -24,7 +24,7 @@ impl Command for ExportDef {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_extern.rs

@@ -9,7 +9,7 @@ impl Command for ExportExtern {
         "export extern"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Define an extern and export it from a module."
     }
 
@@ -21,7 +21,7 @@ impl Command for ExportExtern {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_module.rs

@@ -9,7 +9,7 @@ impl Command for ExportModule {
         "export module"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Export a custom module from a module."
     }
 
@@ -26,7 +26,7 @@ impl Command for ExportModule {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/export_use.rs

@@ -9,7 +9,7 @@ impl Command for ExportUse {
         "export use"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Use definitions from a module and export them from this module."
     }
 
@@ -25,7 +25,7 @@ impl Command for ExportUse {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/extern_.rs

@@ -9,7 +9,7 @@ impl Command for Extern {
         "extern"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Define a signature for an external command."
     }
 
@@ -21,7 +21,7 @@ impl Command for Extern {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/for_.rs

@@ -9,7 +9,7 @@ impl Command for For {
         "for"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Loop over a range."
     }
 
@@ -32,7 +32,7 @@ impl Command for For {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/hide.rs

@@ -21,11 +21,11 @@ impl Command for Hide {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Hide definitions in the current scope."
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         r#"Definitions are hidden by priority: First aliases, then custom commands.
 
 This command is a parser keyword. For details, check:

crates/nu-cmd-lang/src/core_commands/hide_env.rs

@@ -25,7 +25,7 @@ impl Command for HideEnv {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Hide environment variables in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/if_.rs

@@ -14,7 +14,7 @@ impl Command for If {
         "if"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Conditionally run a block."
     }
 
@@ -41,7 +41,7 @@ impl Command for If {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/ignore.rs

@@ -9,7 +9,7 @@ impl Command for Ignore {
         "ignore"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Ignore the output of the previous command in the pipeline."
     }
 

crates/nu-cmd-lang/src/core_commands/let_.rs

@@ -9,7 +9,7 @@ impl Command for Let {
         "let"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create a variable and give it a value."
     }
 
@@ -26,7 +26,7 @@ impl Command for Let {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/loop_.rs

@@ -9,7 +9,7 @@ impl Command for Loop {
         "loop"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Run a block in a loop."
     }
 
@@ -21,7 +21,7 @@ impl Command for Loop {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/match_.rs

@@ -11,7 +11,7 @@ impl Command for Match {
         "match"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Conditionally run a block on a matched value."
     }
 
@@ -27,7 +27,7 @@ impl Command for Match {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/module.rs

@@ -9,7 +9,7 @@ impl Command for Module {
         "module"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Define a custom module."
     }
 
@@ -26,7 +26,7 @@ impl Command for Module {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/mut_.rs

@@ -9,7 +9,7 @@ impl Command for Mut {
         "mut"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create a mutable variable and give it a value."
     }
 
@@ -26,7 +26,7 @@ impl Command for Mut {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/overlay/command.rs

@@ -15,11 +15,11 @@ impl Command for Overlay {
             .input_output_types(vec![(Type::Nothing, Type::String)])
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Commands for manipulating overlays."
     }
 
-    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
 

crates/nu-cmd-lang/src/core_commands/overlay/hide.rs

@@ -9,7 +9,7 @@ impl Command for OverlayHide {
         "overlay hide"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Hide an active overlay."
     }
 
@@ -31,7 +31,7 @@ impl Command for OverlayHide {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/overlay/list.rs

@@ -8,7 +8,7 @@ impl Command for OverlayList {
         "overlay list"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "List all active overlays."
     }
 
@@ -18,7 +18,7 @@ impl Command for OverlayList {
             .input_output_types(vec![(Type::Nothing, Type::List(Box::new(Type::String)))])
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         "The overlays are listed in the order they were activated."
     }
 

crates/nu-cmd-lang/src/core_commands/overlay/new.rs

@@ -9,7 +9,7 @@ impl Command for OverlayNew {
         "overlay new"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create an empty overlay."
     }
 
@@ -27,7 +27,7 @@ impl Command for OverlayNew {
             .category(Category::Core)
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         r#"The command will first create an empty module, then add it as an overlay.
 
 This command is a parser keyword. For details, check:

crates/nu-cmd-lang/src/core_commands/overlay/use_.rs

@@ -14,7 +14,7 @@ impl Command for OverlayUse {
         "overlay use"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Use definitions from a module as an overlay."
     }
 
@@ -45,7 +45,7 @@ impl Command for OverlayUse {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/return_.rs

@@ -9,7 +9,7 @@ impl Command for Return {
         "return"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Return early from a function."
     }
 
@@ -24,7 +24,7 @@ impl Command for Return {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/scope/aliases.rs

@@ -15,7 +15,7 @@ impl Command for ScopeAliases {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output info on the aliases in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/command.rs

@@ -15,7 +15,7 @@ impl Command for Scope {
             .allow_variants_without_examples(true)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Commands for getting info about what is in scope."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/commands.rs

@@ -15,7 +15,7 @@ impl Command for ScopeCommands {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output info on the commands in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/engine_stats.rs

@@ -15,7 +15,7 @@ impl Command for ScopeEngineStats {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output stats on the engine in the current state."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/externs.rs

@@ -15,7 +15,7 @@ impl Command for ScopeExterns {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output info on the known externals in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/modules.rs

@@ -15,7 +15,7 @@ impl Command for ScopeModules {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output info on the modules in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/scope/variables.rs

@@ -15,7 +15,7 @@ impl Command for ScopeVariables {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Output info on the variables in the current scope."
     }
 

crates/nu-cmd-lang/src/core_commands/try_.rs

@@ -9,7 +9,7 @@ impl Command for Try {
         "try"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Try to run a block, if it fails optionally run a catch closure."
     }
 
@@ -31,7 +31,7 @@ impl Command for Try {
             .category(Category::Core)
     }
 
-    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"#
     }

crates/nu-cmd-lang/src/core_commands/use_.rs

@@ -14,7 +14,7 @@ impl Command for Use {
         "use"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Use definitions from a module, making them available in your shell."
     }
 
@@ -35,7 +35,7 @@ impl Command for Use {
         vec!["module", "import", "include", "scope"]
     }
 
-    fn extra_usage(&self) -> &str {
+    fn extra_description(&self) -> &str {
         r#"See `help std` for the standard library module.
 See `help modules` to list all available modules.
 

crates/nu-cmd-lang/src/core_commands/version.rs

@@ -21,7 +21,7 @@ impl Command for Version {
             .category(Category::Core)
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Display Nu version, and its build configuration."
     }
 

crates/nu-cmd-lang/src/core_commands/while_.rs

@@ -9,7 +9,7 @@ impl Command for While {
         "while"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Conditionally run a block in a loop."
     }
 
@@ -30,7 +30,7 @@ impl Command for While {
         vec!["loop"]
     }
 
-    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"#
     }