From 0318631d1a6c1a65fd2104bd98edfb4d9bf48e63 Mon Sep 17 00:00:00 2001
From: josh11b <josh11b@users.noreply.github.com>
Date: Thu, 2 Nov 2023 17:25:05 -0700
Subject: [PATCH] Clarify some comments (#3360)

---
 toolchain/check/node_stack.h  | 6 ++----
 toolchain/parse/node_kind.def | 3 +++
 toolchain/parse/state.def     | 2 +-
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/toolchain/check/node_stack.h b/toolchain/check/node_stack.h
index 9d08a47a017d..1f2655b130ac 100644
--- a/toolchain/check/node_stack.h
+++ b/toolchain/check/node_stack.h
@@ -168,12 +168,10 @@ class NodeStack {
     return std::nullopt;
   }
 
-  // Peeks at the parse node of the given depth in the stack, or by default the
-  // top node.
+  // Peeks at the parse node of the top of the name stack.
   auto PeekParseNode() const -> Parse::Node { return stack_.back().parse_node; }
 
-  // Peeks at the ID of node at the given depth in the stack, or by default the
-  // top node.
+  // Peeks at the ID associated with the top of the name stack.
   template <Parse::NodeKind::RawEnumType RequiredParseKind>
   auto Peek() const -> auto {
     Entry back = stack_.back();
diff --git a/toolchain/parse/node_kind.def b/toolchain/parse/node_kind.def
index 6ce865ccfa31..296b0dcdd6d9 100644
--- a/toolchain/parse/node_kind.def
+++ b/toolchain/parse/node_kind.def
@@ -89,6 +89,9 @@ CARBON_PARSE_NODE_KIND_CHILD_COUNT(NameExpression, 0, CARBON_TOKEN(Identifier))
 //    is documented separately.
 // -  `_optional_` if this node may be present or omitted in valid parses,
 //    depending on which tokens are in the source code.
+//
+// There is generally a close correspondence between handling of tokens and the
+// creation of non-external nodes in a given block.
 
 // ----------------------------------------------------------------------------
 
diff --git a/toolchain/parse/state.def b/toolchain/parse/state.def
index 636619eef4c3..73cd79151335 100644
--- a/toolchain/parse/state.def
+++ b/toolchain/parse/state.def
@@ -242,9 +242,9 @@ CARBON_PARSE_STATE(DeclarationScopeLoop)
 // responsible for handling chaining.
 //
 // The forms of this are:
-// - Designated names in structs.
 // - Qualified names in declarations.
 // - Member access expressions.
+// - Designated names in structs.
 //
 // Declarations and expressions have qualifiers such as `x.y`, while structs
 // have designators such as `.z`.