Document public types in nu-protocol (#12906)

- **Doc-comment public `nu-protocol` modules**
- **Doccomment argument/signature/call stuff**
- **Doccomment cell path types**
- **Doccomment expression stuff**
- **Doccomment import patterns**
- **Doccomment pattern matching AST nodes**

crates/nu-protocol/src/alias.rs

@@ -4,10 +4,16 @@ use crate::{
     PipelineData, ShellError, Signature,
 };
 
+/// Command wrapper of an alias.
+///
+/// Our current aliases are implemented as wrapping commands
+/// This has some limitations compared to text-substitution macro aliases but can reliably use more
+/// of our machinery
 #[derive(Clone)]
 pub struct Alias {
     pub name: String,
-    pub command: Option<Box<dyn Command>>, // None if external call
+    /// Wrapped inner [`Command`]. `None` if alias of external call
+    pub command: Option<Box<dyn Command>>,
     pub wrapped_call: Expression,
     pub usage: String,
     pub extra_usage: String,

crates/nu-protocol/src/ast/call.rs

@@ -7,12 +7,30 @@ use crate::{
     ShellError, Span, Spanned, Value,
 };
 
+/// Parsed command arguments
+///
+/// Primarily for internal commands
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum Argument {
+    /// A positional argument (that is not [`Argument::Spread`])
+    ///
+    /// ```nushell
+    /// my_cmd positional
+    /// ```
     Positional(Expression),
+    /// A named/flag argument that can optionally receive a [`Value`] as an [`Expression`]
+    ///
+    /// The optional second `Spanned<String>` refers to the short-flag version if used
+    /// ```nushell
+    /// my_cmd --flag
+    /// my_cmd -f
+    /// my_cmd --flag-with-value <expr>
+    /// ```
     Named((Spanned<String>, Option<Spanned<String>>, Option<Expression>)),
-    Unknown(Expression), // unknown argument used in "fall-through" signatures
-    Spread(Expression),  // a list spread to fill in rest arguments
+    /// unknown argument used in "fall-through" signatures
+    Unknown(Expression),
+    /// a list spread to fill in rest arguments
+    Spread(Expression),
 }
 
 impl Argument {
@@ -47,12 +65,24 @@ impl Argument {
     }
 }
 
+/// Argument passed to an external command
+///
+/// Here the parsing rules slightly differ to directly pass strings to the external process
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum ExternalArgument {
+    /// Expression that needs to be evaluated to turn into an external process argument
     Regular(Expression),
+    /// Occurrence of a `...` spread operator that needs to be expanded
     Spread(Expression),
 }
 
+/// Parsed call of a `Command`
+///
+/// As we also implement some internal keywords in terms of the `Command` trait, this type stores the passed arguments as [`Expression`].
+/// Some of its methods lazily evaluate those to [`Value`] while others return the underlying
+/// [`Expression`].
+///
+/// For further utilities check the `nu_engine::CallExt` trait that extends [`Call`]
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Call {
     /// identifier of the declaration to call

crates/nu-protocol/src/ast/cell_path.rs

@@ -3,16 +3,23 @@ use crate::Span;
 use serde::{Deserialize, Serialize};
 use std::{cmp::Ordering, fmt::Display};
 
+/// One level of access of a [`CellPath`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum PathMember {
+    /// Accessing a member by string (i.e. columns of a table or [`Record`](crate::Record))
     String {
         val: String,
         span: Span,
+        /// If marked as optional don't throw an error if not found but perform default handling
+        /// (e.g. return `Value::Nothing`)
         optional: bool,
     },
+    /// Accessing a member by index (i.e. row of a table or item in a list)
     Int {
         val: usize,
         span: Span,
+        /// If marked as optional don't throw an error if not found but perform default handling
+        /// (e.g. return `Value::Nothing`)
         optional: bool,
     },
 }
@@ -143,6 +150,18 @@ impl PartialOrd for PathMember {
     }
 }
 
+/// Represents the potentially nested access to fields/cells of a container type
+///
+/// In our current implementation for table access the order of row/column is commutative.
+/// This limits the number of possible rows to select in one [`CellPath`] to 1 as it could
+/// otherwise be ambiguous
+///
+/// ```nushell
+/// col1.0
+/// 0.col1
+/// col2
+/// 42
+/// ```
 #[derive(Debug, Clone, PartialEq, PartialOrd, Serialize, Deserialize)]
 pub struct CellPath {
     pub members: Vec<PathMember>,

crates/nu-protocol/src/ast/expr.rs

@@ -9,6 +9,7 @@ use crate::{
     ast::ImportPattern, engine::StateWorkingSet, BlockId, OutDest, Signature, Span, VarId,
 };
 
+/// An [`Expression`] AST node
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum Expr {
     Bool(bool),
@@ -127,6 +128,7 @@ impl Expr {
     }
 }
 
+/// Expressions permitted inside a record expression/literal
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum RecordItem {
     /// A key: val mapping
@@ -135,6 +137,7 @@ pub enum RecordItem {
     Spread(Span, Expression),
 }
 
+/// Expressions permitted inside a list expression/literal
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum ListItem {
     /// A normal expression

crates/nu-protocol/src/ast/expression.rs

@@ -6,6 +6,7 @@ use crate::{
 use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 
+/// Wrapper around [`Expr`]
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Expression {
     pub expr: Expr,

crates/nu-protocol/src/ast/import_pattern.rs

@@ -3,10 +3,14 @@ use serde::{Deserialize, Serialize};
 use crate::{ModuleId, Span, VarId};
 use std::collections::HashSet;
 
+/// possible patterns after the first module level in an [`ImportPattern`].
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum ImportPatternMember {
+    /// Wildcard import of items
     Glob { span: Span },
+    /// single specific module or item
     Name { name: Vec<u8>, span: Span },
+    /// list of items
     List { names: Vec<(Vec<u8>, Span)> },
 }
 
@@ -31,6 +35,7 @@ impl ImportPatternMember {
     }
 }
 
+/// The first item of a `use` statement needs to specify an explicit module
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ImportPatternHead {
     pub name: Vec<u8>,
@@ -38,6 +43,7 @@ pub struct ImportPatternHead {
     pub span: Span,
 }
 
+/// The pattern specifying modules in a `use` statement
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ImportPattern {
     pub head: ImportPatternHead,

crates/nu-protocol/src/ast/match_pattern.rs

@@ -2,6 +2,7 @@ use super::Expression;
 use crate::{Span, VarId};
 use serde::{Deserialize, Serialize};
 
+/// AST Node for match arm with optional match guard
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct MatchPattern {
     pub pattern: Pattern,
@@ -15,18 +16,28 @@ impl MatchPattern {
     }
 }
 
+/// AST Node for pattern matching rules
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub enum Pattern {
+    /// Destructuring of records
     Record(Vec<(String, MatchPattern)>),
+    /// List destructuring
     List(Vec<MatchPattern>),
+    /// Matching against a literal
     // TODO: it would be nice if this didn't depend on AST
     // maybe const evaluation can get us to a Value instead?
     Value(Box<Expression>),
+    /// binding to a variable
     Variable(VarId),
+    /// the `pattern1 \ pattern2` or-pattern
     Or(Vec<MatchPattern>),
-    Rest(VarId), // the ..$foo pattern
-    IgnoreRest,  // the .. pattern
-    IgnoreValue, // the _ pattern
+    /// the `..$foo` pattern
+    Rest(VarId),
+    /// the `..` pattern
+    IgnoreRest,
+    /// the `_` pattern
+    IgnoreValue,
+    /// Failed parsing of a pattern
     Garbage,
 }
 

crates/nu-protocol/src/ast/mod.rs

@@ -1,3 +1,4 @@
+//! Types representing parsed Nushell code (the Abstract Syntax Tree)
 mod block;
 mod call;
 mod cell_path;
@@ -9,7 +10,7 @@ mod match_pattern;
 mod operator;
 mod pipeline;
 mod range;
-pub mod table;
+mod table;
 mod unit;
 mod value_with_unit;
 

crates/nu-protocol/src/config/mod.rs

@@ -1,3 +1,4 @@
+//! Module containing the internal representation of user configuration
 use self::completer::*;
 use self::helper::*;
 use self::hooks::*;

crates/nu-protocol/src/debugger/mod.rs

@@ -1,3 +1,4 @@
+//! Module containing the trait to instrument the engine for debugging and profiling
 pub mod debugger_trait;
 pub mod profiler;
 

crates/nu-protocol/src/engine/mod.rs

@@ -1,3 +1,4 @@
+//! Representation of the engine state and many of the details that implement the scoping
 mod argument;
 mod cached_file;
 mod call;

crates/nu-protocol/src/errors/cli_error.rs

@@ -1,3 +1,6 @@
+//! This module manages the step of turning error types into printed error messages
+//!
+//! Relies on the `miette` crate for pretty layout
 use crate::{
     engine::{EngineState, StateWorkingSet},
     ErrorStyle,

crates/nu-protocol/src/eval_base.rs

@@ -1,3 +1,4 @@
+//! Foundational [`Eval`] trait allowing dispatch between const-eval and regular evaluation
 use crate::{
     ast::{
         eval_operator, Assignment, Bits, Boolean, Call, Comparison, Expr, Expression,

crates/nu-protocol/src/eval_const.rs

@@ -1,3 +1,7 @@
+//! Implementation of const-evaluation
+//!
+//! This enables you to assign `const`-constants and execute parse-time code dependent on this.
+//! e.g. `source $my_const`
 use crate::{
     ast::{Assignment, Block, Call, Expr, Expression, ExternalArgument},
     debugger::{DebugContext, WithoutDebug},

crates/nu-protocol/src/pipeline/byte_stream.rs

@@ -1,3 +1,4 @@
+//! Module managing the streaming of raw bytes between pipeline elements
 use crate::{
     process::{ChildPipe, ChildProcess, ExitStatus},
     ErrSpan, IntoSpanned, OutDest, PipelineData, ShellError, Signals, Span, Type, Value,

crates/nu-protocol/src/pipeline/list_stream.rs

@@ -1,3 +1,7 @@
+//! Module managing the streaming of individual [`Value`]s as a [`ListStream`] between pipeline
+//! elements
+//!
+//! For more general infos regarding our pipelining model refer to [`PipelineData`]
 use crate::{Config, PipelineData, ShellError, Signals, Span, Value};
 use std::fmt::Debug;
 

crates/nu-protocol/src/process/mod.rs

@@ -1,3 +1,4 @@
+//! Handling of external subprocesses
 mod child;
 mod exit_status;
 

crates/nu-protocol/src/signature.rs

@@ -5,6 +5,7 @@ use crate::{
 use serde::{Deserialize, Serialize};
 use std::fmt::Write;
 
+/// The signature definition of a named flag that either accepts a value or acts as a toggle flag
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Flag {
     pub long: String,
@@ -18,6 +19,7 @@ pub struct Flag {
     pub default_value: Option<Value>,
 }
 
+/// The signature definition for a positional argument
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct PositionalArg {
     pub name: String,
@@ -29,6 +31,7 @@ pub struct PositionalArg {
     pub default_value: Option<Value>,
 }
 
+/// Command categories
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum Category {
     Bits,
@@ -102,6 +105,7 @@ impl std::fmt::Display for Category {
     }
 }
 
+/// Signature information of a [`Command`]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Signature {
     pub name: String,

crates/nu-protocol/src/span.rs

@@ -1,3 +1,4 @@
+//! [`Span`] to point to sections of source code and the [`Spanned`] wrapper type
 use crate::SpanId;
 use miette::SourceSpan;
 use serde::{Deserialize, Serialize};

crates/nu-protocol/src/value/record.rs

@@ -1,3 +1,4 @@
+//! Our insertion ordered map-type [`Record`]
 use std::{iter::FusedIterator, ops::RangeBounds};
 
 use crate::{ShellError, Span, Value};