Merge pull request #882 from jonathandturner/arg_descs

Add descriptions to arguments

src/commands/cd.rs

@@ -10,7 +10,11 @@ impl WholeStreamCommand for CD {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("cd").optional("directory", SyntaxShape::Path)
+        Signature::build("cd").optional(
+            "directory",
+            SyntaxShape::Path,
+            "the directory to change to",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/config.rs

@@ -26,12 +26,16 @@ impl WholeStreamCommand for Config {
 
     fn signature(&self) -> Signature {
         Signature::build("config")
-            .named("load", SyntaxShape::Path)
-            .named("set", SyntaxShape::Any)
-            .named("get", SyntaxShape::Any)
-            .named("remove", SyntaxShape::Any)
-            .switch("clear")
-            .switch("path")
+            .named(
+                "load",
+                SyntaxShape::Path,
+                "load the config from the path give",
+            )
+            .named("set", SyntaxShape::Any, "set a value in the config")
+            .named("get", SyntaxShape::Any, "get a value from the config")
+            .named("remove", SyntaxShape::Any, "remove a value from the config")
+            .switch("clear", "clear the config")
+            .switch("path", "return the path to the config file")
     }
 
     fn usage(&self) -> &str {

src/commands/cp.rs

@@ -21,10 +21,9 @@ impl PerItemCommand for Cpy {
 
     fn signature(&self) -> Signature {
         Signature::build("cp")
-            .required("src", SyntaxShape::Pattern)
-            .required("dst", SyntaxShape::Path)
-            .named("file", SyntaxShape::Any)
-            .switch("recursive")
+            .required("src", SyntaxShape::Pattern, "the place to copy from")
+            .required("dst", SyntaxShape::Path, "the place to copy to")
+            .switch("recursive", "copy recursively through subdirectories")
     }
 
     fn usage(&self) -> &str {

src/commands/date.rs

@@ -17,7 +17,9 @@ impl WholeStreamCommand for Date {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("date").switch("utc").switch("local")
+        Signature::build("date")
+            .switch("utc", "use universal time (UTC)")
+            .switch("local", "use the local time")
     }
 
     fn usage(&self) -> &str {

src/commands/echo.rs

@@ -12,7 +12,7 @@ impl PerItemCommand for Echo {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("echo").rest(SyntaxShape::Any)
+        Signature::build("echo").rest(SyntaxShape::Any, "the values to echo")
     }
 
     fn usage(&self) -> &str {

src/commands/enter.rs

@@ -14,7 +14,11 @@ impl PerItemCommand for Enter {
     }
 
     fn signature(&self) -> registry::Signature {
-        Signature::build("enter").required("location", SyntaxShape::Path)
+        Signature::build("enter").required(
+            "location",
+            SyntaxShape::Path,
+            "the location to create a new shell from",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/exit.rs

@@ -11,7 +11,7 @@ impl WholeStreamCommand for Exit {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("exit").switch("now")
+        Signature::build("exit").switch("now", "exit out of the shell immediately")
     }
 
     fn usage(&self) -> &str {

src/commands/fetch.rs

@@ -19,8 +19,12 @@ impl PerItemCommand for Fetch {
 
     fn signature(&self) -> Signature {
         Signature::build(self.name())
-            .required("path", SyntaxShape::Path)
-            .switch("raw")
+            .required(
+                "path",
+                SyntaxShape::Path,
+                "the URL to fetch the contents from",
+            )
+            .switch("raw", "fetch contents as text rather than a table")
     }
 
     fn usage(&self) -> &str {

src/commands/first.rs

@@ -16,7 +16,11 @@ impl WholeStreamCommand for First {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("first").optional("rows", SyntaxShape::Int)
+        Signature::build("first").optional(
+            "rows",
+            SyntaxShape::Int,
+            "starting from the front, the number of rows to return",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/from_csv.rs

@@ -16,7 +16,8 @@ impl WholeStreamCommand for FromCSV {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("from-csv").switch("headerless")
+        Signature::build("from-csv")
+            .switch("headerless", "don't treat the first row as column names")
     }
 
     fn usage(&self) -> &str {

src/commands/from_json.rs

@@ -15,7 +15,7 @@ impl WholeStreamCommand for FromJSON {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("from-json").switch("objects")
+        Signature::build("from-json").switch("objects", "treat each line as a separate value")
     }
 
     fn usage(&self) -> &str {

src/commands/from_ssv.rs

@@ -21,8 +21,12 @@ impl WholeStreamCommand for FromSSV {
 
     fn signature(&self) -> Signature {
         Signature::build(STRING_REPRESENTATION)
-            .switch("headerless")
-            .named("minimum-spaces", SyntaxShape::Int)
+            .switch("headerless", "don't treat the first row as column names")
+            .named(
+                "minimum-spaces",
+                SyntaxShape::Int,
+                "the mininum spaces to separate columns",
+            )
     }
 
     fn usage(&self) -> &str {

src/commands/from_tsv.rs

@@ -16,7 +16,8 @@ impl WholeStreamCommand for FromTSV {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("from-tsv").switch("headerless")
+        Signature::build("from-tsv")
+            .switch("headerless", "don't treat the first row as column names")
     }
 
     fn usage(&self) -> &str {

src/commands/get.rs

@@ -20,8 +20,15 @@ impl WholeStreamCommand for Get {
 
     fn signature(&self) -> Signature {
         Signature::build("get")
-            .required("member", SyntaxShape::ColumnPath)
-            .rest(SyntaxShape::ColumnPath)
+            .required(
+                "member",
+                SyntaxShape::ColumnPath,
+                "the path to the data to get",
+            )
+            .rest(
+                SyntaxShape::ColumnPath,
+                "optionally return additional data by path",
+            )
     }
 
     fn usage(&self) -> &str {

src/commands/group_by.rs

@@ -16,7 +16,11 @@ impl WholeStreamCommand for GroupBy {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("group-by").required("column_name", SyntaxShape::String)
+        Signature::build("group-by").required(
+            "column_name",
+            SyntaxShape::String,
+            "the name of the column to group by",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/help.rs

@@ -12,7 +12,7 @@ impl PerItemCommand for Help {
     }
 
     fn signature(&self) -> registry::Signature {
-        Signature::build("help").rest(SyntaxShape::Any)
+        Signature::build("help").rest(SyntaxShape::Any, "the name of command(s) to get help on")
     }
 
     fn usage(&self) -> &str {
@@ -65,8 +65,8 @@ impl PerItemCommand for Help {
                             one_liner.push_str("{flags} ");
                         }
 
-                        for positional in signature.positional {
-                            match positional {
+                        for positional in &signature.positional {
+                            match &positional.0 {
                                 PositionalType::Mandatory(name, _m) => {
                                     one_liner.push_str(&format!("<{}> ", name));
                                 }
@@ -77,25 +77,66 @@ impl PerItemCommand for Help {
                         }
 
                         if signature.rest_positional.is_some() {
-                            one_liner.push_str(" ...args");
+                            one_liner.push_str(&format!(" ...args",));
                         }
+
                         long_desc.push_str(&format!("\nUsage:\n  > {}\n", one_liner));
 
+                        if signature.positional.len() > 0 || signature.rest_positional.is_some() {
+                            long_desc.push_str("\nparameters:\n");
+                            for positional in signature.positional {
+                                match positional.0 {
+                                    PositionalType::Mandatory(name, _m) => {
+                                        long_desc
+                                            .push_str(&format!("  <{}> {}\n", name, positional.1));
+                                    }
+                                    PositionalType::Optional(name, _o) => {
+                                        long_desc
+                                            .push_str(&format!("  ({}) {}\n", name, positional.1));
+                                    }
+                                }
+                            }
+                            if signature.rest_positional.is_some() {
+                                long_desc.push_str(&format!(
+                                    "  ...args{} {}\n",
+                                    if signature.rest_positional.is_some() {
+                                        ":"
+                                    } else {
+                                        ""
+                                    },
+                                    signature.rest_positional.unwrap().1
+                                ));
+                            }
+                        }
                         if signature.named.len() > 0 {
                             long_desc.push_str("\nflags:\n");
                             for (flag, ty) in signature.named {
-                                match ty {
+                                match ty.0 {
                                     NamedType::Switch => {
-                                        long_desc.push_str(&format!("  --{}\n", flag));
+                                        long_desc.push_str(&format!(
+                                            "  --{}{} {}\n",
+                                            flag,
+                                            if ty.1.len() > 0 { ":" } else { "" },
+                                            ty.1
+                                        ));
                                     }
                                     NamedType::Mandatory(m) => {
                                         long_desc.push_str(&format!(
-                                            "  --{} <{}> (required parameter)\n",
-                                            flag, m
+                                            "  --{} <{}> (required parameter){} {}\n",
+                                            flag,
+                                            m,
+                                            if ty.1.len() > 0 { ":" } else { "" },
+                                            ty.1
                                         ));
                                     }
                                     NamedType::Optional(o) => {
-                                        long_desc.push_str(&format!("  --{} <{}>\n", flag, o));
+                                        long_desc.push_str(&format!(
+                                            "  --{} <{}>{} {}\n",
+                                            flag,
+                                            o,
+                                            if ty.1.len() > 0 { ":" } else { "" },
+                                            ty.1
+                                        ));
                                     }
                                 }
                             }

src/commands/last.rs

@@ -16,7 +16,11 @@ impl WholeStreamCommand for Last {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("last").optional("rows", SyntaxShape::Number)
+        Signature::build("last").optional(
+            "rows",
+            SyntaxShape::Number,
+            "starting from the back, the number of rows to return",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/ls.rs

@@ -16,7 +16,11 @@ impl WholeStreamCommand for LS {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("ls").optional("path", SyntaxShape::Pattern)
+        Signature::build("ls").optional(
+            "path",
+            SyntaxShape::Pattern,
+            "a path to get the directory contents from",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/mkdir.rs

@@ -17,7 +17,7 @@ impl PerItemCommand for Mkdir {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("mkdir").rest(SyntaxShape::Path)
+        Signature::build("mkdir").rest(SyntaxShape::Path, "the name(s) of the path(s) to create")
     }
 
     fn usage(&self) -> &str {

src/commands/mv.rs

@@ -20,9 +20,16 @@ impl PerItemCommand for Move {
 
     fn signature(&self) -> Signature {
         Signature::build("mv")
-            .required("source", SyntaxShape::Pattern)
-            .required("destination", SyntaxShape::Path)
-            .named("file", SyntaxShape::Any)
+            .required(
+                "source",
+                SyntaxShape::Pattern,
+                "the location to move files/directories from",
+            )
+            .required(
+                "destination",
+                SyntaxShape::Path,
+                "the location to move files/directories to",
+            )
     }
 
     fn usage(&self) -> &str {

src/commands/nth.rs

@@ -16,7 +16,11 @@ impl WholeStreamCommand for Nth {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("nth").required("row number", SyntaxShape::Any)
+        Signature::build("nth").required(
+            "row number",
+            SyntaxShape::Any,
+            "the number of the row to return",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/open.rs

@@ -16,8 +16,12 @@ impl PerItemCommand for Open {
 
     fn signature(&self) -> Signature {
         Signature::build(self.name())
-            .required("path", SyntaxShape::Path)
-            .switch("raw")
+            .required(
+                "path",
+                SyntaxShape::Path,
+                "the file path to load values from",
+            )
+            .switch("raw", "load content as a string insead of a table")
     }
 
     fn usage(&self) -> &str {

src/commands/pick.rs

@@ -17,7 +17,7 @@ impl WholeStreamCommand for Pick {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("pick").rest(SyntaxShape::Any)
+        Signature::build("pick").rest(SyntaxShape::Any, "the columns to select from the table")
     }
 
     fn usage(&self) -> &str {

src/commands/pivot.rs

@@ -21,9 +21,12 @@ impl WholeStreamCommand for Pivot {
 
     fn signature(&self) -> Signature {
         Signature::build("pivot")
-            .switch("header-row")
-            .switch("ignore-titles")
-            .rest(SyntaxShape::String)
+            .switch("header-row", "treat the first row as column names")
+            .switch("ignore-titles", "don't pivot the column names into values")
+            .rest(
+                SyntaxShape::String,
+                "the names to give columns once pivoted",
+            )
     }
 
     fn usage(&self) -> &str {

src/commands/post.rs

@@ -25,13 +25,25 @@ impl PerItemCommand for Post {
 
     fn signature(&self) -> Signature {
         Signature::build(self.name())
-            .required("path", SyntaxShape::Any)
-            .required("body", SyntaxShape::Any)
-            .named("user", SyntaxShape::Any)
-            .named("password", SyntaxShape::Any)
-            .named("content-type", SyntaxShape::Any)
-            .named("content-length", SyntaxShape::Any)
-            .switch("raw")
+            .required("path", SyntaxShape::Any, "the URL to post to")
+            .required("body", SyntaxShape::Any, "the contents of the post body")
+            .named("user", SyntaxShape::Any, "the username when authenticating")
+            .named(
+                "password",
+                SyntaxShape::Any,
+                "the password when authenticating",
+            )
+            .named(
+                "content-type",
+                SyntaxShape::Any,
+                "the MIME type of content to post",
+            )
+            .named(
+                "content-length",
+                SyntaxShape::Any,
+                "the length of the content being posted",
+            )
+            .switch("raw", "return values as a string instead of a table")
     }
 
     fn usage(&self) -> &str {

src/commands/reject.rs

@@ -16,7 +16,7 @@ impl WholeStreamCommand for Reject {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("reject").rest(SyntaxShape::Member)
+        Signature::build("reject").rest(SyntaxShape::Member, "the names of columns to remove")
     }
 
     fn usage(&self) -> &str {

src/commands/rm.rs

@@ -21,13 +21,16 @@ impl PerItemCommand for Remove {
 
     fn signature(&self) -> Signature {
         Signature::build("rm")
-            .required("path", SyntaxShape::Pattern)
-            .switch("trash")
-            .switch("recursive")
+            .required("path", SyntaxShape::Pattern, "the file path to remove")
+            .switch(
+                "trash",
+                "use the platform's recycle bin instead of permanently deleting",
+            )
+            .switch("recursive", "delete subdirectories recursively")
     }
 
     fn usage(&self) -> &str {
-        "Remove a file. Append '--recursive' to remove directories and '--trash' for seding it to system recycle bin"
+        "Remove a file"
     }
 
     fn run(

src/commands/save.rs

@@ -93,8 +93,11 @@ impl WholeStreamCommand for Save {
 
     fn signature(&self) -> Signature {
         Signature::build("save")
-            .optional("path", SyntaxShape::Path)
-            .switch("raw")
+            .optional("path", SyntaxShape::Path, "the path to save contents to")
+            .switch(
+                "raw",
+                "treat values as-is rather than auto-converting based on file extension",
+            )
     }
 
     fn usage(&self) -> &str {

src/commands/skip_while.rs

@@ -17,7 +17,11 @@ impl WholeStreamCommand for SkipWhile {
 
     fn signature(&self) -> Signature {
         Signature::build("skip-while")
-            .required("condition", SyntaxShape::Block)
+            .required(
+                "condition",
+                SyntaxShape::Block,
+                "the condition that must be met to continue skipping",
+            )
             .filter()
     }
 

src/commands/sort_by.rs

@@ -15,7 +15,7 @@ impl WholeStreamCommand for SortBy {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("sort-by").rest(SyntaxShape::String)
+        Signature::build("sort-by").rest(SyntaxShape::String, "the column(s) to sort by")
     }
 
     fn usage(&self) -> &str {

src/commands/split_column.rs

@@ -21,9 +21,13 @@ impl WholeStreamCommand for SplitColumn {
 
     fn signature(&self) -> Signature {
         Signature::build("split-column")
-            .required("separator", SyntaxShape::Any)
-            .switch("collapse-empty")
-            .rest(SyntaxShape::Member)
+            .required(
+                "separator",
+                SyntaxShape::Any,
+                "the character that denotes what separates columns",
+            )
+            .switch("collapse-empty", "remove empty columns")
+            .rest(SyntaxShape::Member, "column names to give the new columns")
     }
 
     fn usage(&self) -> &str {

src/commands/split_row.rs

@@ -17,7 +17,11 @@ impl WholeStreamCommand for SplitRow {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("split-row").required("separator", SyntaxShape::Any)
+        Signature::build("split-row").required(
+            "separator",
+            SyntaxShape::Any,
+            "the character that denotes what separates rows",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/table.rs

@@ -11,7 +11,11 @@ impl WholeStreamCommand for Table {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("table").named("start_number", SyntaxShape::Number)
+        Signature::build("table").named(
+            "start_number",
+            SyntaxShape::Number,
+            "row number to start viewing from",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/to_csv.rs

@@ -16,7 +16,10 @@ impl WholeStreamCommand for ToCSV {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("to-csv").switch("headerless")
+        Signature::build("to-csv").switch(
+            "headerless",
+            "do not output the columns names as the first row",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/to_tsv.rs

@@ -16,7 +16,10 @@ impl WholeStreamCommand for ToTSV {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("to-tsv").switch("headerless")
+        Signature::build("to-tsv").switch(
+            "headerless",
+            "do not output the column names as the first row",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/where_.rs

@@ -12,7 +12,11 @@ impl PerItemCommand for Where {
     }
 
     fn signature(&self) -> registry::Signature {
-        Signature::build("where").required("condition", SyntaxShape::Block)
+        Signature::build("where").required(
+            "condition",
+            SyntaxShape::Block,
+            "the condition that must match",
+        )
     }
 
     fn usage(&self) -> &str {

src/commands/which_.rs

@@ -13,7 +13,11 @@ impl WholeStreamCommand for Which {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("which").required("name", SyntaxShape::Any)
+        Signature::build("which").required(
+            "name",
+            SyntaxShape::Any,
+            "the name of the command to find the path to",
+        )
     }
 
     fn usage(&self) -> &str {

src/data/command.rs

@@ -45,12 +45,12 @@ fn signature_dict(signature: Signature, tag: impl Into<Tag>) -> Tagged<Value> {
     let mut sig = TaggedListBuilder::new(&tag);
 
     for arg in signature.positional.iter() {
-        let is_required = match arg {
+        let is_required = match arg.0 {
             PositionalType::Mandatory(_, _) => true,
             PositionalType::Optional(_, _) => false,
         };
 
-        sig.insert_tagged(for_spec(arg.name(), "argument", is_required, &tag));
+        sig.insert_tagged(for_spec(arg.0.name(), "argument", is_required, &tag));
     }
 
     if let Some(_) = signature.rest_positional {
@@ -59,7 +59,7 @@ fn signature_dict(signature: Signature, tag: impl Into<Tag>) -> Tagged<Value> {
     }
 
     for (name, ty) in signature.named.iter() {
-        match ty {
+        match ty.0 {
             NamedType::Mandatory(_) => sig.insert_tagged(for_spec(name, "flag", true, &tag)),
             NamedType::Optional(_) => sig.insert_tagged(for_spec(name, "flag", false, &tag)),
             NamedType::Switch => sig.insert_tagged(for_spec(name, "switch", false, &tag)),

src/parser/parse_command.rs

@@ -25,7 +25,7 @@ pub fn parse_command_tail(
     for (name, kind) in &config.named {
         trace!(target: "nu::parse", "looking for {} : {:?}", name, kind);
 
-        match kind {
+        match &kind.0 {
             NamedType::Switch => {
                 let flag = extract_switch(name, tail, context.source());
 
@@ -92,12 +92,12 @@ pub fn parse_command_tail(
     for arg in &config.positional {
         trace!(target: "nu::parse", "Processing positional {:?}", arg);
 
-        match arg {
+        match &arg.0 {
             PositionalType::Mandatory(..) => {
                 if tail.at_end_possible_ws() {
                     return Err(ShellError::argument_error(
                         config.name.clone(),
-                        ArgumentError::MissingMandatoryPositional(arg.name().to_string()),
+                        ArgumentError::MissingMandatoryPositional(arg.0.name().to_string()),
                         Tag {
                             span: command_span,
                             anchor: None,
@@ -113,14 +113,14 @@ pub fn parse_command_tail(
             }
         }
 
-        let result = expand_expr(&spaced(arg.syntax_type()), tail, context)?;
+        let result = expand_expr(&spaced(arg.0.syntax_type()), tail, context)?;
 
         positional.push(result);
     }
 
     trace_remaining("after positional", tail.clone(), context.source());
 
-    if let Some(syntax_type) = config.rest_positional {
+    if let Some((syntax_type, _)) = config.rest_positional {
         let mut out = vec![];
 
         loop {
@@ -207,7 +207,7 @@ impl ColorSyntax for CommandTailShape {
         for (name, kind) in &signature.named {
             trace!(target: "nu::color_syntax", "looking for {} : {:?}", name, kind);
 
-            match kind {
+            match &kind.0 {
                 NamedType::Switch => {
                     match token_nodes.extract(|t| t.as_flag(name, context.source())) {
                         Some((pos, flag)) => args.insert(pos, vec![flag.color()]),
@@ -300,7 +300,7 @@ impl ColorSyntax for CommandTailShape {
         for arg in &signature.positional {
             trace!("Processing positional {:?}", arg);
 
-            match arg {
+            match arg.0 {
                 PositionalType::Mandatory(..) => {
                     if token_nodes.at_end() {
                         break;
@@ -327,7 +327,7 @@ impl ColorSyntax for CommandTailShape {
 
                         // If no match, we should roll back any whitespace we chomped
                         color_fallible_syntax(
-                            &arg.syntax_type(),
+                            &arg.0.syntax_type(),
                             token_nodes,
                             context,
                             &mut shapes,
@@ -343,7 +343,7 @@ impl ColorSyntax for CommandTailShape {
 
         trace_remaining("after positional", token_nodes.clone(), context.source());
 
-        if let Some(syntax_type) = signature.rest_positional {
+        if let Some((syntax_type, _)) = signature.rest_positional {
             loop {
                 if token_nodes.at_end_possible_ws() {
                     break;
@@ -407,7 +407,7 @@ impl ColorSyntax for CommandTailShape {
         for (name, kind) in &signature.named {
             trace!(target: "nu::color_syntax", "looking for {} : {:?}", name, kind);
 
-            match kind {
+            match &kind.0 {
                 NamedType::Switch => {
                     match token_nodes.extract(|t| t.as_flag(name, context.source())) {
                         Some((pos, flag)) => args.insert(pos, vec![flag.color()]),
@@ -502,7 +502,7 @@ impl ColorSyntax for CommandTailShape {
         for arg in &signature.positional {
             trace!("Processing positional {:?}", arg);
 
-            match arg {
+            match &arg.0 {
                 PositionalType::Mandatory(..) => {
                     if token_nodes.at_end() {
                         break;
@@ -527,7 +527,7 @@ impl ColorSyntax for CommandTailShape {
                         color_syntax(&MaybeSpaceShape, token_nodes, context);
 
                         // If no match, we should roll back any whitespace we chomped
-                        color_fallible_syntax(&arg.syntax_type(), token_nodes, context)?;
+                        color_fallible_syntax(&arg.0.syntax_type(), token_nodes, context)?;
 
                         Ok(())
                     });
@@ -539,7 +539,7 @@ impl ColorSyntax for CommandTailShape {
 
         trace_remaining("after positional", token_nodes.clone(), context.source());
 
-        if let Some(syntax_type) = signature.rest_positional {
+        if let Some((syntax_type, _)) = signature.rest_positional {
             loop {
                 if token_nodes.at_end_possible_ws() {
                     break;

src/parser/registry.rs

@@ -58,17 +58,19 @@ impl PositionalType {
     }
 }
 
+type Description = String;
+
 #[derive(Debug, Serialize, Deserialize, Clone, new)]
 pub struct Signature {
     pub name: String,
     #[new(default)]
     pub usage: String,
     #[new(default)]
-    pub positional: Vec<PositionalType>,
+    pub positional: Vec<(PositionalType, Description)>,
     #[new(value = "None")]
-    pub rest_positional: Option<SyntaxShape>,
+    pub rest_positional: Option<(SyntaxShape, Description)>,
     #[new(default)]
-    pub named: IndexMap<String, NamedType>,
+    pub named: IndexMap<String, (NamedType, Description)>,
     #[new(value = "false")]
     pub is_filter: bool,
 }
@@ -83,23 +85,42 @@ impl Signature {
         self
     }
 
-    pub fn required(mut self, name: impl Into<String>, ty: impl Into<SyntaxShape>) -> Signature {
-        self.positional
-            .push(PositionalType::Mandatory(name.into(), ty.into()));
+    pub fn required(
+        mut self,
+        name: impl Into<String>,
+        ty: impl Into<SyntaxShape>,
+        desc: impl Into<String>,
+    ) -> Signature {
+        self.positional.push((
+            PositionalType::Mandatory(name.into(), ty.into()),
+            desc.into(),
+        ));
 
         self
     }
 
-    pub fn optional(mut self, name: impl Into<String>, ty: impl Into<SyntaxShape>) -> Signature {
-        self.positional
-            .push(PositionalType::Optional(name.into(), ty.into()));
+    pub fn optional(
+        mut self,
+        name: impl Into<String>,
+        ty: impl Into<SyntaxShape>,
+        desc: impl Into<String>,
+    ) -> Signature {
+        self.positional.push((
+            PositionalType::Optional(name.into(), ty.into()),
+            desc.into(),
+        ));
 
         self
     }
 
-    pub fn named(mut self, name: impl Into<String>, ty: impl Into<SyntaxShape>) -> Signature {
+    pub fn named(
+        mut self,
+        name: impl Into<String>,
+        ty: impl Into<SyntaxShape>,
+        desc: impl Into<String>,
+    ) -> Signature {
         self.named
-            .insert(name.into(), NamedType::Optional(ty.into()));
+            .insert(name.into(), (NamedType::Optional(ty.into()), desc.into()));
 
         self
     }
@@ -108,15 +129,17 @@ impl Signature {
         mut self,
         name: impl Into<String>,
         ty: impl Into<SyntaxShape>,
+        desc: impl Into<String>,
     ) -> Signature {
         self.named
-            .insert(name.into(), NamedType::Mandatory(ty.into()));
+            .insert(name.into(), (NamedType::Mandatory(ty.into()), desc.into()));
 
         self
     }
 
-    pub fn switch(mut self, name: impl Into<String>) -> Signature {
-        self.named.insert(name.into(), NamedType::Switch);
+    pub fn switch(mut self, name: impl Into<String>, desc: impl Into<String>) -> Signature {
+        self.named
+            .insert(name.into(), (NamedType::Switch, desc.into()));
 
         self
     }
@@ -126,8 +149,8 @@ impl Signature {
         self
     }
 
-    pub fn rest(mut self, ty: SyntaxShape) -> Signature {
-        self.rest_positional = Some(ty);
+    pub fn rest(mut self, ty: SyntaxShape, desc: impl Into<String>) -> Signature {
+        self.rest_positional = Some((ty, desc.into()));
         self
     }
 }

src/plugins/add.rs

@@ -53,10 +53,13 @@ impl Add {
 impl Plugin for Add {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("add")
-            .desc("Add a new field to the table.")
-            .required("Field", SyntaxShape::ColumnPath)
-            .required("Value", SyntaxShape::String)
-            .rest(SyntaxShape::String)
+            .desc("Add a new column to the table.")
+            .required("column", SyntaxShape::ColumnPath, "the column name to add")
+            .required(
+                "value",
+                SyntaxShape::String,
+                "the value to give the cell(s)",
+            )
             .filter())
     }
 

src/plugins/binaryview.rs

@@ -16,7 +16,7 @@ impl Plugin for BinaryView {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("binaryview")
             .desc("Autoview of binary data.")
-            .switch("lores"))
+            .switch("lores", "use low resolution output mode"))
     }
 
     fn sink(&mut self, call_info: CallInfo, input: Vec<Tagged<Value>>) {

src/plugins/edit.rs

@@ -48,8 +48,16 @@ impl Plugin for Edit {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("edit")
             .desc("Edit an existing column to have a new value.")
-            .required("Field", SyntaxShape::ColumnPath)
-            .required("Value", SyntaxShape::String)
+            .required(
+                "Field",
+                SyntaxShape::ColumnPath,
+                "the name of the column to edit",
+            )
+            .required(
+                "Value",
+                SyntaxShape::String,
+                "the new value to give the cell(s)",
+            )
             .filter())
     }
 

src/plugins/embed.rs

@@ -28,7 +28,7 @@ impl Plugin for Embed {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("embed")
             .desc("Embeds a new field to the table.")
-            .optional("field", SyntaxShape::String)
+            .optional("field", SyntaxShape::String, "the name of the new column")
             .filter())
     }
 

src/plugins/inc.rs

@@ -137,10 +137,10 @@ impl Plugin for Inc {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("inc")
             .desc("Increment a value or version. Optionally use the column of a table.")
-            .switch("major")
-            .switch("minor")
-            .switch("patch")
-            .rest(SyntaxShape::ColumnPath)
+            .switch("major", "increment the major version (eg 1.2.1 -> 2.0.0)")
+            .switch("minor", "increment the minor version (eg 1.2.1 -> 1.3.0)")
+            .switch("patch", "increment the patch version (eg 1.2.1 -> 1.2.2)")
+            .rest(SyntaxShape::ColumnPath, "the column(s) to update")
             .filter())
     }
 

src/plugins/match.rs

@@ -22,8 +22,8 @@ impl Plugin for Match {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("match")
             .desc("filter rows by regex")
-            .required("member", SyntaxShape::Member)
-            .required("regex", SyntaxShape::String)
+            .required("member", SyntaxShape::Member, "the column name to match")
+            .required("regex", SyntaxShape::String, "the regex to match with")
             .filter())
     }
     fn begin_filter(&mut self, call_info: CallInfo) -> Result<Vec<ReturnValue>, ShellError> {

src/plugins/skip.rs

@@ -17,7 +17,7 @@ impl Plugin for Skip {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("skip")
             .desc("Skip a number of rows")
-            .rest(SyntaxShape::Number)
+            .rest(SyntaxShape::Number, "the number of rows to skip")
             .filter())
     }
     fn begin_filter(&mut self, call_info: CallInfo) -> Result<Vec<ReturnValue>, ShellError> {

src/plugins/str.rs

@@ -128,11 +128,11 @@ impl Str {
 impl Plugin for Str {
     fn config(&mut self) -> Result<Signature, ShellError> {
         Ok(Signature::build("str")
-            .desc("Apply string function. Optional use the field of a table")
-            .switch("downcase")
-            .switch("upcase")
-            .switch("to-int")
-            .rest(SyntaxShape::ColumnPath)
+            .desc("Apply string function. Optional use the column of a table")
+            .switch("downcase", "convert string to lowercase")
+            .switch("upcase", "convert string to uppercase")
+            .switch("to-int", "convert string to integer")
+            .rest(SyntaxShape::ColumnPath, "the column(s) to convert")
             .filter())
     }