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-command/tests/commands/help.rs

@@ -36,8 +36,8 @@ fn help_aliases() {
 }
 
 #[test]
-fn help_alias_usage_1() {
-    Playground::setup("help_alias_usage_1", |dirs, sandbox| {
+fn help_alias_description_1() {
+    Playground::setup("help_alias_description_1", |dirs, sandbox| {
         sandbox.with_files(&[FileWithContent(
             "spam.nu",
             r#"
@@ -48,7 +48,7 @@ fn help_alias_usage_1() {
 
         let code = &[
             "source spam.nu",
-            "help aliases | where name == SPAM | get 0.usage",
+            "help aliases | where name == SPAM | get 0.description",
         ];
         let actual = nu!(cwd: dirs.test(), nu_repl_code(code));
 
@@ -57,10 +57,10 @@ fn help_alias_usage_1() {
 }
 
 #[test]
-fn help_alias_usage_2() {
+fn help_alias_description_2() {
     let code = &[
         "alias SPAM = print 'spam'  # line2",
-        "help aliases | where name == SPAM | get 0.usage",
+        "help aliases | where name == SPAM | get 0.description",
     ];
     let actual = nu!(nu_repl_code(code));
 
@@ -68,8 +68,8 @@ fn help_alias_usage_2() {
 }
 
 #[test]
-fn help_alias_usage_3() {
-    Playground::setup("help_alias_usage_3", |dirs, sandbox| {
+fn help_alias_description_3() {
+    Playground::setup("help_alias_description_3", |dirs, sandbox| {
         sandbox.with_files(&[FileWithContent(
             "spam.nu",
             r#"
@@ -80,7 +80,7 @@ fn help_alias_usage_3() {
 
         let code = &[
             "source spam.nu",
-            "help aliases | where name == SPAM | get 0.usage",
+            "help aliases | where name == SPAM | get 0.description",
         ];
         let actual = nu!(cwd: dirs.test(), nu_repl_code(code));
 
@@ -121,7 +121,7 @@ fn help_alias_name_f() {
             "#,
         )]);
 
-        let code = &["source spam.nu", "help aliases -f SPAM | get 0.usage"];
+        let code = &["source spam.nu", "help aliases -f SPAM | get 0.description"];
         let actual = nu!(cwd: dirs.test(), nu_repl_code(code));
 
         assert!(actual.out.contains("line1"));
@@ -172,8 +172,8 @@ fn help_export_alias_name_multi_word() {
 }
 
 #[test]
-fn help_module_usage_1() {
-    Playground::setup("help_module_usage", |dirs, sandbox| {
+fn help_module_description_1() {
+    Playground::setup("help_module_description", |dirs, sandbox| {
         sandbox.with_files(&[FileWithContent(
             "spam.nu",
             r#"
@@ -186,7 +186,7 @@ fn help_module_usage_1() {
 
         let code = &[
             "source spam.nu",
-            "help modules | where name == SPAM | get 0.usage",
+            "help modules | where name == SPAM | get 0.description",
         ];
         let actual = nu!(cwd: dirs.test(), nu_repl_code(code));
 
@@ -260,11 +260,13 @@ fn help_module_sorted_aliases() {
 }
 
 #[test]
-fn help_usage_extra_usage_command() {
-    Playground::setup("help_usage_extra_usage_command", |dirs, sandbox| {
-        sandbox.with_files(&[FileWithContent(
-            "spam.nu",
-            r#"
+fn help_description_extra_description_command() {
+    Playground::setup(
+        "help_description_extra_description_command",
+        |dirs, sandbox| {
+            sandbox.with_files(&[FileWithContent(
+                "spam.nu",
+                r#"
                 # module_line1
                 #
                 # module_line2
@@ -274,34 +276,37 @@ fn help_usage_extra_usage_command() {
                 # def_line2
                 export def foo [] {}
             "#,
-        )]);
+            )]);
 
-        let actual = nu!(cwd: dirs.test(), "use spam.nu *; help modules spam");
-        assert!(actual.out.contains("module_line1"));
-        assert!(actual.out.contains("module_line2"));
+            let actual = nu!(cwd: dirs.test(), "use spam.nu *; help modules spam");
+            assert!(actual.out.contains("module_line1"));
+            assert!(actual.out.contains("module_line2"));
 
-        let actual = nu!(cwd: dirs.test(),
-            "use spam.nu *; help modules | where name == spam | get 0.usage");
-        assert!(actual.out.contains("module_line1"));
-        assert!(!actual.out.contains("module_line2"));
+            let actual = nu!(cwd: dirs.test(),
+            "use spam.nu *; help modules | where name == spam | get 0.description");
+            assert!(actual.out.contains("module_line1"));
+            assert!(!actual.out.contains("module_line2"));
 
-        let actual = nu!(cwd: dirs.test(), "use spam.nu *; help commands foo");
-        assert!(actual.out.contains("def_line1"));
-        assert!(actual.out.contains("def_line2"));
+            let actual = nu!(cwd: dirs.test(), "use spam.nu *; help commands foo");
+            assert!(actual.out.contains("def_line1"));
+            assert!(actual.out.contains("def_line2"));
 
-        let actual = nu!(cwd: dirs.test(),
-            "use spam.nu *; help commands | where name == foo | get 0.usage");
-        assert!(actual.out.contains("def_line1"));
-        assert!(!actual.out.contains("def_line2"));
-    })
+            let actual = nu!(cwd: dirs.test(),
+            "use spam.nu *; help commands | where name == foo | get 0.description");
+            assert!(actual.out.contains("def_line1"));
+            assert!(!actual.out.contains("def_line2"));
+        },
+    )
 }
 
 #[test]
-fn help_usage_extra_usage_alias() {
-    Playground::setup("help_usage_extra_usage_alias", |dirs, sandbox| {
-        sandbox.with_files(&[FileWithContent(
-            "spam.nu",
-            r#"
+fn help_description_extra_description_alias() {
+    Playground::setup(
+        "help_description_extra_description_alias",
+        |dirs, sandbox| {
+            sandbox.with_files(&[FileWithContent(
+                "spam.nu",
+                r#"
                 # module_line1
                 #
                 # module_line2
@@ -311,26 +316,27 @@ fn help_usage_extra_usage_alias() {
                 # alias_line2
                 export alias bar = echo 'bar'
             "#,
-        )]);
+            )]);
 
-        let actual = nu!(cwd: dirs.test(), "use spam.nu *; help modules spam");
-        assert!(actual.out.contains("module_line1"));
-        assert!(actual.out.contains("module_line2"));
+            let actual = nu!(cwd: dirs.test(), "use spam.nu *; help modules spam");
+            assert!(actual.out.contains("module_line1"));
+            assert!(actual.out.contains("module_line2"));
 
-        let actual = nu!(cwd: dirs.test(),
-            "use spam.nu *; help modules | where name == spam | get 0.usage");
-        assert!(actual.out.contains("module_line1"));
-        assert!(!actual.out.contains("module_line2"));
+            let actual = nu!(cwd: dirs.test(),
+            "use spam.nu *; help modules | where name == spam | get 0.description");
+            assert!(actual.out.contains("module_line1"));
+            assert!(!actual.out.contains("module_line2"));
 
-        let actual = nu!(cwd: dirs.test(), "use spam.nu *; help aliases bar");
-        assert!(actual.out.contains("alias_line1"));
-        assert!(actual.out.contains("alias_line2"));
+            let actual = nu!(cwd: dirs.test(), "use spam.nu *; help aliases bar");
+            assert!(actual.out.contains("alias_line1"));
+            assert!(actual.out.contains("alias_line2"));
 
-        let actual = nu!(cwd: dirs.test(),
-            "use spam.nu *; help aliases | where name == bar | get 0.usage");
-        assert!(actual.out.contains("alias_line1"));
-        assert!(!actual.out.contains("alias_line2"));
-    })
+            let actual = nu!(cwd: dirs.test(),
+            "use spam.nu *; help aliases | where name == bar | get 0.description");
+            assert!(actual.out.contains("alias_line1"));
+            assert!(!actual.out.contains("alias_line2"));
+        },
+    )
 }
 
 #[test]

crates/nu-command/tests/main.rs

@@ -197,7 +197,7 @@ fn no_search_term_duplicates() {
 }
 
 #[test]
-fn usage_end_period() {
+fn description_end_period() {
     let ctx = crate::create_default_context();
     let decls = ctx.get_decls_sorted(true);
     let mut failures = Vec::new();
@@ -205,22 +205,22 @@ fn usage_end_period() {
     for (name_bytes, decl_id) in decls {
         let cmd = ctx.get_decl(decl_id);
         let cmd_name = String::from_utf8_lossy(&name_bytes);
-        let usage = cmd.usage();
+        let description = cmd.description();
 
-        if !usage.ends_with('.') {
-            failures.push(format!("{cmd_name}: \"{usage}\""));
+        if !description.ends_with('.') {
+            failures.push(format!("{cmd_name}: \"{description}\""));
         }
     }
 
     assert!(
         failures.is_empty(),
-        "Command usage does not end with a period:\n{}",
+        "Command description does not end with a period:\n{}",
         failures.join("\n")
     );
 }
 
 #[test]
-fn usage_start_uppercase() {
+fn description_start_uppercase() {
     let ctx = crate::create_default_context();
     let decls = ctx.get_decls_sorted(true);
     let mut failures = Vec::new();
@@ -228,19 +228,19 @@ fn usage_start_uppercase() {
     for (name_bytes, decl_id) in decls {
         let cmd = ctx.get_decl(decl_id);
         let cmd_name = String::from_utf8_lossy(&name_bytes);
-        let usage = cmd.usage();
+        let description = cmd.description();
 
-        // Check lowercase to allow usage to contain syntax like:
+        // Check lowercase to allow description to contain syntax like:
         //
         // "`$env.FOO = ...`"
-        if usage.starts_with(|u: char| u.is_lowercase()) {
-            failures.push(format!("{cmd_name}: \"{usage}\""));
+        if description.starts_with(|u: char| u.is_lowercase()) {
+            failures.push(format!("{cmd_name}: \"{description}\""));
         }
     }
 
     assert!(
         failures.is_empty(),
-        "Command usage does not start with an uppercase letter:\n{}",
+        "Command description does not start with an uppercase letter:\n{}",
         failures.join("\n")
     );
 }