Misc comment cleanups (#6200)

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

---------

Co-authored-by: Richard Smith <[email protected]>

Author: jonmeow

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);
   }
 

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

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;

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.

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;
   }

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>;

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 =