From 6d9ee96584a78e53075a05f4cf9101cb9950c1f3 Mon Sep 17 00:00:00 2001
From: Jon Ross-Perkins <jperkins@google.com>
Date: Mon, 13 Oct 2025 11:49:48 -0700
Subject: [PATCH] Misc comment cleanups (#6200)

Just trying to apply a few scattered comment improvements that AI helped
flag.

---------

Co-authored-by: Richard Smith <richard@metafoo.co.uk>
---
 common/array_stack.h                   | 2 +-
 common/exe_path.h                      | 5 +++--
 testing/file_test/file_test_base.h     | 4 ++--
 toolchain/base/canonical_value_store.h | 3 ++-
 toolchain/base/index_base.h            | 2 +-
 toolchain/base/kind_switch.h           | 8 ++++++--
 toolchain/sem_ir/file.h                | 2 +-
 7 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/common/array_stack.h b/common/array_stack.h
index f2e4b66a3afd..2c672ef9698b 100644
--- a/common/array_stack.h
+++ b/common/array_stack.h
@@ -82,7 +82,7 @@ class ArrayStack {
   // Adds multiple values to the top array on the stack.
   auto AppendToTop(llvm::ArrayRef<ValueT> values) -> void {
     CARBON_CHECK(!array_offsets_.empty(),
-                 "Must call PushArray before PushValues.");
+                 "Must call PushArray before AppendToTop.");
     llvm::append_range(values_, values);
   }
 
diff --git a/common/exe_path.h b/common/exe_path.h
index 8bd10d69011b..9474b568ad48 100644
--- a/common/exe_path.h
+++ b/common/exe_path.h
@@ -13,8 +13,9 @@ namespace Carbon {
 // `argv0` is required to be null-terminated.
 //
 // A simplistic approach -- if the provided string isn't already a valid path,
-// we look it up in the PATH environment variable. Doesn't resolve any symlinks
-// and if it fails, returns the main executable path.
+// we look it up in the PATH environment variable. Doesn't resolve any symlinks.
+// If it doesn't find a value based on `argv[0]`, returns the main executable
+// path.
 auto FindExecutablePath(const char* argv0) -> std::string;
 
 }  // namespace Carbon
diff --git a/testing/file_test/file_test_base.h b/testing/file_test/file_test_base.h
index a9c4bb907b9a..80738075dd53 100644
--- a/testing/file_test/file_test_base.h
+++ b/testing/file_test/file_test_base.h
@@ -85,8 +85,8 @@ class FileTestBase {
   }
 
   // Returns a regex to match the default file when a line may not be present.
-  // May return nullptr if unused. If GetLineNumberReplacements returns an entry
-  // with has_file=false, this is required.
+  // May return `std::nullopt` if unused. If `GetLineNumberReplacements` returns
+  // an entry with `has_file=false`, this is required.
   virtual auto GetDefaultFileRE(llvm::ArrayRef<llvm::StringRef> /*filenames*/)
       const -> std::optional<RE2> {
     return std::nullopt;
diff --git a/toolchain/base/canonical_value_store.h b/toolchain/base/canonical_value_store.h
index 827fad9ac3b2..264c4fbe579c 100644
--- a/toolchain/base/canonical_value_store.h
+++ b/toolchain/base/canonical_value_store.h
@@ -30,7 +30,8 @@ class CanonicalValueStore {
   using RefType = ValueStoreTypes<ValueT>::RefType;
   using ConstRefType = ValueStoreTypes<ValueT>::ConstRefType;
 
-  // Stores a canonical copy of the value and returns an ID to reference it.
+  // Stores a canonical copy of the value and returns an ID to reference it. If
+  // the value is already in the store, returns the ID of the existing value.
   auto Add(ValueType value) -> IdT;
 
   // Returns the value for an ID.
diff --git a/toolchain/base/index_base.h b/toolchain/base/index_base.h
index 3e36c4f59d0d..5b53261a1a71 100644
--- a/toolchain/base/index_base.h
+++ b/toolchain/base/index_base.h
@@ -140,7 +140,7 @@ class IndexIterator
     return *this;
   }
 
-  // Prints the raw token index.
+  // Prints the raw index.
   auto Print(llvm::raw_ostream& output) const -> void {
     output << index_.index;
   }
diff --git a/toolchain/base/kind_switch.h b/toolchain/base/kind_switch.h
index 4db4c05e9b77..396c0601ee12 100644
--- a/toolchain/base/kind_switch.h
+++ b/toolchain/base/kind_switch.h
@@ -222,8 +222,12 @@ consteval auto ForCase() -> auto {
   }
 }
 
-// Given `CARBON_KIND_SWITCH(value)` and `CARBON_KIND(CaseT name)` this
-// generates `value.As<CaseT>()`.
+// Given `CARBON_KIND_SWITCH(value)` and `CARBON_KIND(CaseT name)` this converts
+// the `value` to `CaseT`.
+//
+// For types with a `kind()` accessor this uses `value.As<CaseT>`.
+//
+// For `std::variant<...>` this uses `std::get<CaseT>(value)`.
 template <typename CaseFnT, typename SwitchT>
 auto Cast(SwitchT&& kind_switch_value) -> decltype(auto) {
   using CaseT = llvm::function_traits<CaseFnT>::template arg_t<0>;
diff --git a/toolchain/sem_ir/file.h b/toolchain/sem_ir/file.h
index 1b9b4484f221..94450cf24b53 100644
--- a/toolchain/sem_ir/file.h
+++ b/toolchain/sem_ir/file.h
@@ -64,7 +64,7 @@ using ExprRegionStore = ValueStore<ExprRegionId, ExprRegion>;
 
 using CustomLayoutStore = BlockValueStore<CustomLayoutId, uint64_t>;
 
-// Provides semantic analysis on a Parse::Tree.
+// The semantic IR for a single file.
 class File : public Printable<File> {
  public:
   using IdentifiedFacetTypeStore =