More comments about LitExpr::LitPath and its parsing.

apollo-federation/src/sources/connect/json_selection/lit_expr.rs

@@ -40,6 +40,19 @@ pub(crate) enum LitExpr {
     Object(IndexMap<WithRange<Key>, WithRange<LitExpr>>),
     Array(Vec<WithRange<LitExpr>>),
     Path(PathSelection),
+
+    // Whereas the LitExpr::Path variant wraps a PathSelection that obeys the
+    // parsing rules of the outer selection syntax (i.e. default JSONSelection
+    // syntax, not LitExpr syntax), this LitExpr::LitPath variant can be parsed
+    // only as part of a LitExpr, and allows the value at the root of the path
+    // to be any LitExpr literal expression, without needing a $(...) wrapper,
+    // allowing you to write "asdf"->slice(0, 2) when you're already in an
+    // expression parsing context, rather than $(asdf)->slice(0, 2).
+    //
+    // The WithRange<LitExpr> argument is the root expression (never a
+    // LitExpr::Path), and the WithRange<PathList> argument represents the rest
+    // of the path, which is never PathList::Empty, because that would mean the
+    // LitExpr could stand on its own, using one of the other variants.
     LitPath(WithRange<LitExpr>, WithRange<PathList>),
 }
 
@@ -60,6 +73,10 @@ impl LitExpr {
                 // initial $(...) expression wrapper, so you can write
                 // $(123->add(111)) instead of $($(123)->add(111)) when you're
                 // already in a LitExpr parsing context.
+                //
+                // We begin parsing the path at depth 1 rather than 0 because
+                // we've already parsed the initial literal at depth 0, so the
+                // subpath should obey the parsing rules for for depth > 0.
                 match PathList::parse_with_depth(suffix, 1) {
                     Ok((remainder, subpath)) => {
                         if matches!(subpath.as_ref(), PathList::Empty) {