diff --git a/crates/nu-parser/src/parser.rs b/crates/nu-parser/src/parser.rs
index 1ab2f74e3d..5e83d809d3 100644
--- a/crates/nu-parser/src/parser.rs
+++ b/crates/nu-parser/src/parser.rs
@@ -2696,7 +2696,15 @@ pub fn parse_string_strict(working_set: &mut StateWorkingSet, span: Span) -> Exp
     }
 }
 
-//TODO: Handle error case for unknown shapes
+/// Parse the literals of [`Type`]-like [`SyntaxShape`]s including inner types.
+/// Also handles the specification of custom completions with `type@completer`.
+///
+/// Used in:
+/// - `: ` argument type (+completer) positions in signatures
+/// - `type->type` input/output type pairs
+/// - `let name: type` variable type infos
+///
+/// NOTE: Does not provide a mapping to every [`SyntaxShape`]
 pub fn parse_shape_name(
     working_set: &mut StateWorkingSet,
     bytes: &[u8],
@@ -2757,6 +2765,7 @@ pub fn parse_shape_name(
                     return shape;
                 }
             } else {
+                //TODO: Handle error case for unknown shapes
                 working_set.error(ParseError::UnknownType(span));
                 return SyntaxShape::Any;
             }
diff --git a/crates/nu-protocol/src/syntax_shape.rs b/crates/nu-protocol/src/syntax_shape.rs
index 58cdf23f6a..f288f44dd1 100644
--- a/crates/nu-protocol/src/syntax_shape.rs
+++ b/crates/nu-protocol/src/syntax_shape.rs
@@ -1,10 +1,14 @@
+use crate::{DeclId, Type};
+use serde::{Deserialize, Serialize};
 use std::fmt::Display;
 
-use serde::{Deserialize, Serialize};
-
-use crate::{DeclId, Type};
-
-/// 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.
+/// The syntactic shapes that describe how a sequence should be parsed.
+///
+/// This extends beyond [`Type`] which describes how [`Value`](crate::Value)s are represented.
+/// `SyntaxShape`s can describe the parsing rules for arguments to a command.
+/// e.g. [`SyntaxShape::GlobPattern`]/[`SyntaxShape::Filepath`] serve the completer,
+/// but don't have an associated [`Value`](crate::Value)
+/// There are additional `SyntaxShape`s that only make sense in particular expressions or keywords
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum SyntaxShape {
     /// Any syntactic form is allowed
@@ -52,7 +56,9 @@ pub enum SyntaxShape {
     /// A floating point value, eg `1.0`
     Float,
 
-    /// A dotted path to navigate the table (including variable)
+    /// A dotted path including the variable to access items
+    ///
+    /// Fully qualified
     FullCellPath,
 
     /// A glob pattern is allowed, eg `foo*`
@@ -115,6 +121,16 @@ pub enum SyntaxShape {
 }
 
 impl SyntaxShape {
+    /// If possible provide the associated concrete [`Type`]
+    ///
+    /// Note: Some [`SyntaxShape`]s don't have a corresponding [`Value`](crate::Value)
+    /// Here we currently return [`Type::Any`]
+    ///
+    /// ```rust
+    /// use nu_protocol::{SyntaxShape, Type};
+    /// let non_value = SyntaxShape::ImportPattern;
+    /// assert_eq!(non_value.to_type(), Type::Any);
+    /// ```
     pub fn to_type(&self) -> Type {
         let mk_ty = |tys: &[(String, SyntaxShape)]| {
             tys.iter()