Doccomment argument/signature/call stuff

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
+    /// unknown argument used in "fall-through" signatures
-    Spread(Expression),  // a list spread to fill in rest arguments
+    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),
+    /// Occurence 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/signature.rs

@@ -6,6 +6,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,
@@ -19,6 +20,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,
@@ -30,6 +32,7 @@ pub struct PositionalArg {
     pub default_value: Option<Value>,
 }
 
+/// Command categories
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum Category {
     Bits,
@@ -103,6 +106,7 @@ impl std::fmt::Display for Category {
     }
 }
 
+/// Signature information of a [`Command`]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Signature {
     pub name: String,