A few help cleanups (#372)

crates/nu-command/src/core_commands/if_.rs

@@ -2,7 +2,7 @@ use nu_engine::{eval_block, eval_expression};
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    Category, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value,
+    Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value,
 };
 
 #[derive(Clone)]
@@ -19,12 +19,16 @@ impl Command for If {
 
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("if")
-            .required("cond", SyntaxShape::Expression, "condition")
-            .required("then_block", SyntaxShape::Block(Some(vec![])), "then block")
+            .required("cond", SyntaxShape::Expression, "condition to check")
+            .required(
+                "then_block",
+                SyntaxShape::Block(Some(vec![])),
+                "block to run if check succeeds",
+            )
             .optional(
-                "else",
+                "else_expression",
                 SyntaxShape::Keyword(b"else".to_vec(), Box::new(SyntaxShape::Expression)),
-                "optional else followed by else block",
+                "expression or block to run if check fails",
             )
             .category(Category::Core)
     }
@@ -74,4 +78,36 @@ impl Command for If {
             )),
         }
     }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Output a value if a condition matches, otherwise return nothing",
+                example: "if 2 < 3 { 'yes!' }",
+                result: Some(Value::test_string("yes!")),
+            },
+            Example {
+                description: "Output a value if a condition matches, else return another value",
+                example: "if 5 < 3 { 'yes!' } else { 'no!' }",
+                result: Some(Value::test_string("no!")),
+            },
+            Example {
+                description: "Chain multiple if's together",
+                example: "if 5 < 3 { 'yes!' } else if 4 < 5 { 'no!' } else { 'okay!' }",
+                result: Some(Value::test_string("no!")),
+            },
+        ]
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_examples() {
+        use crate::test_examples;
+
+        test_examples(If {})
+    }
 }

crates/nu-command/src/core_commands/let_.rs

@@ -1,7 +1,7 @@
 use nu_engine::eval_expression;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, PipelineData, Signature, SyntaxShape};
+use nu_protocol::{Category, Example, PipelineData, Signature, SyntaxShape};
 
 #[derive(Clone)]
 pub struct Let;
@@ -48,4 +48,31 @@ impl Command for Let {
         stack.add_var(var_id, rhs);
         Ok(PipelineData::new(call.head))
     }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Set a variable to a value",
+                example: "let x = 10",
+                result: None,
+            },
+            Example {
+                description: "Set a variable to the result of an expression",
+                example: "let x = 10 + 100",
+                result: None,
+            },
+        ]
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_examples() {
+        use crate::test_examples;
+
+        test_examples(Let {})
+    }
 }

crates/nu-engine/src/documentation.rs

@@ -1,5 +1,7 @@
 use itertools::Itertools;
-use nu_protocol::{engine::EngineState, Example, Signature, Span, Value};
+use nu_protocol::{
+    engine::EngineState, Example, PositionalArg, Signature, Span, SyntaxShape, Value,
+};
 use std::collections::HashMap;
 
 const COMMANDS_DOCS_DIR: &str = "docs/commands";
@@ -171,10 +173,10 @@ pub fn get_documentation(
     one_liner.push(' ');
 
     for positional in &sig.required_positional {
-        one_liner.push_str(&format!("<{}> ", positional.name));
+        one_liner.push_str(&get_positional_short_name(positional, true));
     }
     for positional in &sig.optional_positional {
-        one_liner.push_str(&format!("({}) ", positional.name));
+        one_liner.push_str(&get_positional_short_name(positional, false));
     }
 
     if sig.rest_positional.is_some() {
@@ -204,10 +206,13 @@ pub fn get_documentation(
     {
         long_desc.push_str("\nParameters:\n");
         for positional in &sig.required_positional {
-            long_desc.push_str(&format!("  <{}> {}\n", positional.name, positional.desc));
+            long_desc.push_str(&format!("  {}: {}\n", positional.name, positional.desc));
         }
         for positional in &sig.optional_positional {
-            long_desc.push_str(&format!("  ({}) {}\n", positional.name, positional.desc));
+            long_desc.push_str(&format!(
+                "  (optional) {}: {}\n",
+                positional.name, positional.desc
+            ));
         }
 
         if let Some(rest_positional) = &sig.rest_positional {
@@ -241,6 +246,25 @@ pub fn get_documentation(
     long_desc
 }
 
+fn get_positional_short_name(arg: &PositionalArg, is_required: bool) -> String {
+    match &arg.shape {
+        SyntaxShape::Keyword(name, ..) => {
+            if is_required {
+                format!("{} <{}> ", String::from_utf8_lossy(name), arg.name)
+            } else {
+                format!("({} <{}>) ", String::from_utf8_lossy(name), arg.name)
+            }
+        }
+        _ => {
+            if is_required {
+                format!("<{}> ", arg.name)
+            } else {
+                format!("({}) ", arg.name)
+            }
+        }
+    }
+}
+
 fn get_flags_section(signature: &Signature) -> String {
     let mut long_desc = String::new();
     long_desc.push_str("\nFlags:\n");

crates/nu-parser/src/flatten.rs

@@ -194,7 +194,7 @@ pub fn flatten_expression(
             output
         }
         Expr::Keyword(_, span, expr) => {
-            let mut output = vec![(*span, FlatShape::Operator)];
+            let mut output = vec![(*span, FlatShape::InternalCall)];
             output.extend(flatten_expression(working_set, expr));
             output
         }