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-plugin/src/lib.rs

@@ -40,7 +40,7 @@
 //!         "my-command"
 //!     }
 //!
-//!     fn usage(&self) -> &str {
+//!     fn description(&self) -> &str {
 //!         todo!();
 //!     }
 //!

crates/nu-plugin/src/plugin/command.rs

@@ -33,7 +33,7 @@ use crate::{EngineInterface, EvaluatedCall, Plugin};
 ///         "lowercase"
 ///     }
 ///
-///     fn usage(&self) -> &str {
+///     fn description(&self) -> &str {
 ///         "Convert each string in a stream to lowercase"
 ///     }
 ///
@@ -92,14 +92,14 @@ pub trait PluginCommand: Sync {
     /// A brief description of usage for the command.
     ///
     /// This should be short enough to fit in completion menus.
-    fn usage(&self) -> &str;
+    fn description(&self) -> &str;
 
     /// Additional documentation for usage of the command.
     ///
     /// This is optional - any arguments documented by [`.signature()`](Self::signature) will be
     /// shown in the help page automatically. However, this can be useful for explaining things that
-    /// would be too brief to include in [`.usage()`](Self::usage) and may span multiple lines.
-    fn extra_usage(&self) -> &str {
+    /// would be too brief to include in [`.description()`](Self::description) and may span multiple lines.
+    fn extra_description(&self) -> &str {
         ""
     }
 
@@ -177,7 +177,7 @@ pub trait PluginCommand: Sync {
 ///         "hello"
 ///     }
 ///
-///     fn usage(&self) -> &str {
+///     fn description(&self) -> &str {
 ///         "Every programmer's favorite greeting"
 ///     }
 ///
@@ -230,14 +230,14 @@ pub trait SimplePluginCommand: Sync {
     /// A brief description of usage for the command.
     ///
     /// This should be short enough to fit in completion menus.
-    fn usage(&self) -> &str;
+    fn description(&self) -> &str;
 
     /// Additional documentation for usage of the command.
     ///
     /// This is optional - any arguments documented by [`.signature()`] will be shown in the help
     /// page automatically. However, this can be useful for explaining things that would be too
-    /// brief to include in [`.usage()`] and may span multiple lines.
-    fn extra_usage(&self) -> &str {
+    /// brief to include in [`.description()`](Self::description) and may span multiple lines.
+    fn extra_description(&self) -> &str {
         ""
     }
 
@@ -301,8 +301,8 @@ where
         <Self as SimplePluginCommand>::examples(self)
     }
 
-    fn extra_usage(&self) -> &str {
-        <Self as SimplePluginCommand>::extra_usage(self)
+    fn extra_description(&self) -> &str {
+        <Self as SimplePluginCommand>::extra_description(self)
     }
 
     fn name(&self) -> &str {
@@ -333,8 +333,8 @@ where
         <Self as SimplePluginCommand>::signature(self)
     }
 
-    fn usage(&self) -> &str {
-        <Self as SimplePluginCommand>::usage(self)
+    fn description(&self) -> &str {
+        <Self as SimplePluginCommand>::description(self)
     }
 }
 
@@ -349,8 +349,8 @@ pub fn create_plugin_signature(command: &(impl PluginCommand + ?Sized)) -> Plugi
         // Add results of trait methods to signature
         command
             .signature()
-            .usage(command.usage())
-            .extra_usage(command.extra_usage())
+            .description(command.description())
+            .extra_description(command.extra_description())
             .search_terms(
                 command
                     .search_terms()

crates/nu-plugin/src/plugin/mod.rs

@@ -69,7 +69,7 @@ pub(crate) const OUTPUT_BUFFER_SIZE: usize = 16384;
 ///         "hello"
 ///     }
 ///
-///     fn usage(&self) -> &str {
+///     fn description(&self) -> &str {
 ///         "Every programmer's favorite greeting"
 ///     }
 ///
@@ -662,10 +662,14 @@ fn print_help(plugin: &impl Plugin, encoder: impl PluginEncoder) {
     plugin.commands().into_iter().for_each(|command| {
         let signature = command.signature();
         let res = write!(help, "\nCommand: {}", command.name())
-            .and_then(|_| writeln!(help, "\nUsage:\n > {}", command.usage()))
+            .and_then(|_| writeln!(help, "\nDescription:\n > {}", command.description()))
             .and_then(|_| {
-                if !command.extra_usage().is_empty() {
-                    writeln!(help, "\nExtra usage:\n > {}", command.extra_usage())
+                if !command.extra_description().is_empty() {
+                    writeln!(
+                        help,
+                        "\nExtra description:\n > {}",
+                        command.extra_description()
+                    )
                 } else {
                     Ok(())
                 }