Doccomment cell path types

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 acces 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>,