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-parser/src/known_external.rs

@@ -9,8 +9,8 @@ use nu_protocol::{
 pub struct KnownExternal {
     pub name: String,
     pub signature: Box<Signature>,
-    pub usage: String,
-    pub extra_usage: String,
+    pub description: String,
+    pub extra_description: String,
 }
 
 impl Command for KnownExternal {
@@ -22,8 +22,8 @@ impl Command for KnownExternal {
         *self.signature.clone()
     }
 
-    fn usage(&self) -> &str {
-        &self.usage
+    fn description(&self) -> &str {
+        &self.description
     }
 
     fn command_type(&self) -> CommandType {

crates/nu-parser/src/parse_keywords.rs

@@ -371,7 +371,7 @@ pub fn parse_def(
 ) -> (Pipeline, Option<(Vec<u8>, DeclId)>) {
     let spans = &lite_command.parts[..];
 
-    let (usage, extra_usage) = working_set.build_usage(&lite_command.comments);
+    let (desc, extra_desc) = working_set.build_desc(&lite_command.comments);
 
     // Checking that the function is used with the correct name
     // Maybe this is not necessary but it is a sanity check
@@ -599,8 +599,8 @@ pub fn parse_def(
             if !has_wrapped {
                 *signature = signature.add_help();
             }
-            signature.usage = usage;
-            signature.extra_usage = extra_usage;
+            signature.description = desc;
+            signature.extra_description = extra_desc;
             signature.allows_unknown_args = has_wrapped;
 
             *declaration = signature.clone().into_block_command(block_id);
@@ -654,7 +654,7 @@ pub fn parse_extern(
 ) -> Pipeline {
     let spans = &lite_command.parts;
 
-    let (usage, extra_usage) = working_set.build_usage(&lite_command.comments);
+    let (description, extra_description) = working_set.build_desc(&lite_command.comments);
 
     // Checking that the function is used with the correct name
     // Maybe this is not necessary but it is a sanity check
@@ -759,8 +759,8 @@ pub fn parse_extern(
                 };
 
                 signature.name.clone_from(&external_name);
-                signature.usage.clone_from(&usage);
-                signature.extra_usage.clone_from(&extra_usage);
+                signature.description.clone_from(&description);
+                signature.extra_description.clone_from(&extra_description);
                 signature.allows_unknown_args = true;
 
                 if let Some(block_id) = body.and_then(|x| x.as_block()) {
@@ -787,8 +787,8 @@ pub fn parse_extern(
 
                     let decl = KnownExternal {
                         name: external_name,
-                        usage,
-                        extra_usage,
+                        description,
+                        extra_description,
                         signature,
                     };
 
@@ -1052,10 +1052,10 @@ pub fn parse_alias(
                 }
             };
 
-            // Tries to build a useful usage string
-            let (usage, extra_usage) = match lite_command.comments.is_empty() {
+            // Tries to build a useful description string
+            let (description, extra_description) = match lite_command.comments.is_empty() {
                 // First from comments, if any are present
-                false => working_set.build_usage(&lite_command.comments),
+                false => working_set.build_desc(&lite_command.comments),
                 // Then from the command itself
                 true => match alias_call.arguments.get(1) {
                     Some(Argument::Positional(Expression {
@@ -1077,8 +1077,8 @@ pub fn parse_alias(
                 name: alias_name,
                 command,
                 wrapped_call,
-                usage,
-                extra_usage,
+                description,
+                extra_description,
             };
 
             working_set.add_decl(Box::new(decl));

crates/nu-parser/tests/test_parser.rs

@@ -16,7 +16,7 @@ impl Command for Let {
         "let"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Create a variable and give it a value."
     }
 
@@ -51,7 +51,7 @@ impl Command for Mut {
         "mut"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Mock mut command."
     }
 
@@ -84,7 +84,7 @@ impl Command for ToCustom {
         "to-custom"
     }
 
-    fn usage(&self) -> &str {
+    fn description(&self) -> &str {
         "Mock converter command."
     }
 
@@ -1903,7 +1903,7 @@ mod input_types {
             "ls"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock ls command."
         }
 
@@ -1930,7 +1930,7 @@ mod input_types {
             "def"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock def command."
         }
 
@@ -1962,7 +1962,7 @@ mod input_types {
             "group-by"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock group-by command."
         }
 
@@ -1983,6 +1983,35 @@ mod input_types {
         }
     }
 
+    #[derive(Clone)]
+    pub struct ToCustom;
+
+    impl Command for ToCustom {
+        fn name(&self) -> &str {
+            "to-custom"
+        }
+
+        fn description(&self) -> &str {
+            "Mock converter command."
+        }
+
+        fn signature(&self) -> nu_protocol::Signature {
+            Signature::build(self.name())
+                .input_output_type(Type::Any, Type::Custom("custom".into()))
+                .category(Category::Custom("custom".into()))
+        }
+
+        fn run(
+            &self,
+            _engine_state: &EngineState,
+            _stack: &mut Stack,
+            _call: &Call,
+            _input: PipelineData,
+        ) -> Result<PipelineData, ShellError> {
+            todo!()
+        }
+    }
+
     #[derive(Clone)]
     pub struct GroupByCustom;
 
@@ -1991,7 +2020,7 @@ mod input_types {
             "group-by"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock custom group-by command."
         }
 
@@ -2022,7 +2051,7 @@ mod input_types {
             "agg"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock custom agg command."
         }
 
@@ -2052,7 +2081,7 @@ mod input_types {
             "min"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock custom min command."
         }
 
@@ -2079,7 +2108,7 @@ mod input_types {
             "with-column"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock custom with-column command."
         }
 
@@ -2109,7 +2138,7 @@ mod input_types {
             "collect"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock custom collect command."
         }
 
@@ -2138,7 +2167,7 @@ mod input_types {
             "if"
         }
 
-        fn usage(&self) -> &str {
+        fn description(&self) -> &str {
             "Mock if command."
         }