From e2e9abab0a51bd2f958bc65b76aaad778ffa135f Mon Sep 17 00:00:00 2001 From: Jonathan Turner Date: Thu, 16 Jan 2020 07:32:46 +1300 Subject: [PATCH] More docs (#1229) * Add some more docs * More docs * More docs * Add more docs --- crates/nu-protocol/src/call_info.rs | 7 +++-- crates/nu-protocol/src/macros.rs | 11 ++++++-- crates/nu-protocol/src/signature.rs | 39 ++++++++++++++++++++++++++ crates/nu-protocol/src/syntax_shape.rs | 12 ++++++++ crates/nu-protocol/src/type_shape.rs | 14 ++++----- 5 files changed, 70 insertions(+), 13 deletions(-) diff --git a/crates/nu-protocol/src/call_info.rs b/crates/nu-protocol/src/call_info.rs index b231248d..3c344294 100644 --- a/crates/nu-protocol/src/call_info.rs +++ b/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>, diff --git a/crates/nu-protocol/src/macros.rs b/crates/nu-protocol/src/macros.rs index 66e7ab13..0b04a0b6 100644 --- a/crates/nu-protocol/src/macros.rs +++ b/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)*) } diff --git a/crates/nu-protocol/src/signature.rs b/crates/nu-protocol/src/signature.rs index b75f6a9d..3751e73a 100644 --- a/crates/nu-protocol/src/signature.rs +++ b/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, + /// The type of values being sent out from the command into the pipeline, if any pub yields: Option, + /// The type of values being read in from the pipeline into the command, if any pub input: Option, + /// 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) -> Signature { Signature { name: name.into(), @@ -114,15 +142,18 @@ impl Signature { } } + /// Create a new signature pub fn build(name: impl Into) -> Signature { Signature::new(name.into()) } + /// Add a description to the signature pub fn desc(mut self, usage: impl Into) -> Signature { self.usage = usage.into(); self } + /// Add a required positional argument to the signature pub fn required( mut self, name: impl Into, @@ -137,6 +168,7 @@ impl Signature { self } + /// Add an optional positional argument to the signature pub fn optional( mut self, name: impl Into, @@ -151,6 +183,7 @@ impl Signature { self } + /// Add an optional named flag argument to the signature pub fn named( mut self, name: impl Into, @@ -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, @@ -175,6 +209,7 @@ impl Signature { self } + /// Add a switch to the signature pub fn switch(mut self, name: impl Into, desc: impl Into) -> 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) -> 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 diff --git a/crates/nu-protocol/src/syntax_shape.rs b/crates/nu-protocol/src/syntax_shape.rs index 3f1d50f8..6ddfe3fc 100644 --- a/crates/nu-protocol/src/syntax_shape.rs +++ b/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", diff --git a/crates/nu-protocol/src/type_shape.rs b/crates/nu-protocol/src/type_shape.rs index aa864416..c43f1f06 100644 --- a/crates/nu-protocol/src/type_shape.rs +++ b/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),