More docs (#1229)

* Add some more docs

* More docs

* More docs

* Add more docs

crates/nu-protocol/src/call_info.rs

@@ -8,13 +8,16 @@ use serde::{Deserialize, Serialize};
 /// Associated information for the call of a command, including the args passed to the command and a tag that spans the name of the command being called
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct CallInfo {
+    /// The arguments associated with this call
     pub args: EvaluatedArgs,
+    /// The tag (underline-able position) of the name of the call itself
     pub name_tag: Tag,
 }
 
 /// The set of positional and named arguments, after their values have been evaluated.
-/// Positional arguments are those who are given as values, without any associated flag. For example, in `foo arg1 arg2`, both `arg1` and `arg2` are positional arguments
-/// Named arguments are those associated with a flag. For example, `foo --given bar` the named argument would be name `given` and the value `bar`.
+///
+/// * Positional arguments are those who are given as values, without any associated flag. For example, in `foo arg1 arg2`, both `arg1` and `arg2` are positional arguments.
+/// * Named arguments are those associated with a flag. For example, `foo --given bar` the named argument would be name `given` and the value `bar`.
 #[derive(Debug, Default, new, Serialize, Deserialize, Clone)]
 pub struct EvaluatedArgs {
     pub positional: Option<Vec<Value>>,

crates/nu-protocol/src/macros.rs

@@ -1,11 +1,16 @@
-// These macros exist to differentiate between intentional writing to stdout
-// and stray printlns left by accident
-
+/// Outputs to standard out
+///
+/// Note: this exists to differentiate between intentional writing to stdout
+/// and stray printlns left by accident
 #[macro_export]
 macro_rules! outln {
     ($($tokens:tt)*) => { println!($($tokens)*) }
 }
 
+/// Outputs to standard error
+///
+/// Note: this exists to differentiate between intentional writing to stdout
+/// and stray printlns left by accident
 #[macro_export]
 macro_rules! errln {
     ($($tokens:tt)*) => { eprintln!($($tokens)*) }

crates/nu-protocol/src/signature.rs

@@ -4,20 +4,28 @@ use indexmap::IndexMap;
 use nu_source::{b, DebugDocBuilder, PrettyDebug, PrettyDebugWithSource};
 use serde::{Deserialize, Serialize};
 
+/// The types of named parameter that a command can have
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub enum NamedType {
+    /// A flag without any associated argument. eg) `foo --bar`
     Switch,
+    /// A mandatory flag, with associated argument. eg) `foo --required xyz`
     Mandatory(SyntaxShape),
+    /// An optional flag, with associated argument. eg) `foo --optional abc`
     Optional(SyntaxShape),
 }
 
+/// The type of positional arguments
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum PositionalType {
+    /// A mandatory postional argument with the expected shape of the value
     Mandatory(String, SyntaxShape),
+    /// An optional positional argument with the expected shape of the value
     Optional(String, SyntaxShape),
 }
 
 impl PrettyDebug for PositionalType {
+    /// Prepare the PositionalType for pretty-printing
     fn pretty(&self) -> DebugDocBuilder {
         match self {
             PositionalType::Mandatory(string, shape) => {
@@ -33,26 +41,32 @@ impl PrettyDebug for PositionalType {
 }
 
 impl PositionalType {
+    /// Helper to create a mandatory positional argument type
     pub fn mandatory(name: &str, ty: SyntaxShape) -> PositionalType {
         PositionalType::Mandatory(name.to_string(), ty)
     }
 
+    /// Helper to create a mandatory positional argument with an "any" type
     pub fn mandatory_any(name: &str) -> PositionalType {
         PositionalType::Mandatory(name.to_string(), SyntaxShape::Any)
     }
 
+    /// Helper to create a mandatory positional argument with a block type
     pub fn mandatory_block(name: &str) -> PositionalType {
         PositionalType::Mandatory(name.to_string(), SyntaxShape::Block)
     }
 
+    /// Helper to create a optional positional argument type
     pub fn optional(name: &str, ty: SyntaxShape) -> PositionalType {
         PositionalType::Optional(name.to_string(), ty)
     }
 
+    /// Helper to create a optional positional argument with an "any" type
     pub fn optional_any(name: &str) -> PositionalType {
         PositionalType::Optional(name.to_string(), SyntaxShape::Any)
     }
 
+    /// Gets the name of the positional argument
     pub fn name(&self) -> &str {
         match self {
             PositionalType::Mandatory(s, _) => s,
@@ -60,6 +74,7 @@ impl PositionalType {
         }
     }
 
+    /// Gets the expected type of a positional argument
     pub fn syntax_type(&self) -> SyntaxShape {
         match *self {
             PositionalType::Mandatory(_, t) => t,
@@ -70,19 +85,31 @@ impl PositionalType {
 
 type Description = String;
 
+/// The full signature of a command. All commands have a signature similar to a function signature.
+/// Commands will use this information to register themselves with Nu's core engine so that the command
+/// can be invoked, help can be displayed, and calls to the command can be error-checked.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct Signature {
+    /// The name of the command. Used when calling the command
     pub name: String,
+    /// Usage instructions about the command
     pub usage: String,
+    /// The list of positional arguments, both required and optional, and their corresponding types and help text
     pub positional: Vec<(PositionalType, Description)>,
+    /// After the positional arguments, a catch-all for the rest of the arguments that might follow, their type, and help text
     pub rest_positional: Option<(SyntaxShape, Description)>,
+    /// The named flags with corresponding type and help text
     pub named: IndexMap<String, (NamedType, Description)>,
+    /// The type of values being sent out from the command into the pipeline, if any
     pub yields: Option<Type>,
+    /// The type of values being read in from the pipeline into the command, if any
     pub input: Option<Type>,
+    /// If the command is expected to filter data, or to consume it (as a sink)
     pub is_filter: bool,
 }
 
 impl PrettyDebugWithSource for Signature {
+    /// Prepare a Signature for pretty-printing
     fn pretty_debug(&self, source: &str) -> DebugDocBuilder {
         b::typed(
             "signature",
@@ -101,6 +128,7 @@ impl PrettyDebugWithSource for Signature {
 }
 
 impl Signature {
+    /// Create a new command signagure with the given name
     pub fn new(name: impl Into<String>) -> Signature {
         Signature {
             name: name.into(),
@@ -114,15 +142,18 @@ impl Signature {
         }
     }
 
+    /// Create a new signature
     pub fn build(name: impl Into<String>) -> Signature {
         Signature::new(name.into())
     }
 
+    /// Add a description to the signature
     pub fn desc(mut self, usage: impl Into<String>) -> Signature {
         self.usage = usage.into();
         self
     }
 
+    /// Add a required positional argument to the signature
     pub fn required(
         mut self,
         name: impl Into<String>,
@@ -137,6 +168,7 @@ impl Signature {
         self
     }
 
+    /// Add an optional positional argument to the signature
     pub fn optional(
         mut self,
         name: impl Into<String>,
@@ -151,6 +183,7 @@ impl Signature {
         self
     }
 
+    /// Add an optional named flag argument to the signature
     pub fn named(
         mut self,
         name: impl Into<String>,
@@ -163,6 +196,7 @@ impl Signature {
         self
     }
 
+    /// Add a required named flag argument to the signature
     pub fn required_named(
         mut self,
         name: impl Into<String>,
@@ -175,6 +209,7 @@ impl Signature {
         self
     }
 
+    /// Add a switch to the signature
     pub fn switch(mut self, name: impl Into<String>, desc: impl Into<String>) -> Signature {
         self.named
             .insert(name.into(), (NamedType::Switch, desc.into()));
@@ -182,21 +217,25 @@ impl Signature {
         self
     }
 
+    /// Set the filter flag for the signature
     pub fn filter(mut self) -> Signature {
         self.is_filter = true;
         self
     }
 
+    /// Set the type for the "rest" of the positional arguments
     pub fn rest(mut self, ty: SyntaxShape, desc: impl Into<String>) -> Signature {
         self.rest_positional = Some((ty, desc.into()));
         self
     }
 
+    /// Add a type for the output of the command to the signature
     pub fn yields(mut self, ty: Type) -> Signature {
         self.yields = Some(ty);
         self
     }
 
+    /// Add a type for the input of the command to the signature
     pub fn input(mut self, ty: Type) -> Signature {
         self.input = Some(ty);
         self

crates/nu-protocol/src/syntax_shape.rs

@@ -1,21 +1,33 @@
 use nu_source::{b, DebugDocBuilder, PrettyDebug};
 use serde::{Deserialize, Serialize};
 
+/// The syntactic shapes that values must match to be passed into a command. You can think of this as the type-checking that occurs when you call a function.
 #[derive(Debug, Copy, Clone, Serialize, Deserialize)]
 pub enum SyntaxShape {
+    /// Any syntactic form is allowed
     Any,
+    /// Strings and string-like bare words are allowed
     String,
+    /// Values that can be the right hand side of a '.'
     Member,
+    /// A dotted path to navigate the table
     ColumnPath,
+    /// Only a numeric (integer or decimal) value is allowed
     Number,
+    /// A range is allowed (eg, `1..3`)
     Range,
+    /// Only an integer value is allowed
     Int,
+    /// A filepath is allowed
     Path,
+    /// A glob pattern is allowed, eg `foo*`
     Pattern,
+    /// A block is allowed, eg `{start this thing}`
     Block,
 }
 
 impl PrettyDebug for SyntaxShape {
+    /// Prepare SyntaxShape for pretty-printing
     fn pretty(&self) -> DebugDocBuilder {
         b::kind(match self {
             SyntaxShape::Any => "any shape",

crates/nu-protocol/src/type_shape.rs

@@ -1,3 +1,9 @@
+///
+/// This file describes the structural types of the nushell system.
+///
+/// Its primary purpose today is to identify "equivalent" values for the purpose
+/// of merging rows into a single table or identify rows in a table that have the
+/// same shape for reflection.
 use crate::value::dict::Dictionary;
 use crate::value::primitive::Primitive;
 use crate::value::range::RangeInclusion;
@@ -9,14 +15,6 @@ use std::collections::BTreeMap;
 use std::fmt::Debug;
 use std::hash::Hash;
 
-/**
-  This file describes the structural types of the nushell system.
-
-  Its primary purpose today is to identify "equivalent" values for the purpose
-  of merging rows into a single table or identify rows in a table that have the
-  same shape for reflection.
-*/
-
 #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize, Deserialize, new)]
 pub struct RangeType {
     from: (Type, RangeInclusion),