clarify comments

src/analysis/lattice.h

@@ -46,15 +46,16 @@ concept Lattice = requires(const L& lattice,
   // Lattices must have elements.
   typename L::Element;
   requires std::copyable<typename L::Element>;
-  // We need to be able to get the bottom element.
+  // Get the bottom element of this lattice.
   { lattice.getBottom() } noexcept -> std::same_as<typename L::Element>;
-  // Elements should be comparable. TODO: use <=> and std::three_way_comparable
-  // once we support C++20 everywhere.
+  // Compare two elements of this lattice. TODO: use <=> and
+  // std::three_way_comparable once we support C++20 everywhere.
   {
     lattice.compare(constElem, constElem)
   } noexcept -> std::same_as<LatticeComparison>;
-  // We need to be able to get the least upper bound of two elements and know
-  // whether any change was made.
+  // Modify `elem` in-place to be the join (aka least upper bound) of `elem` and
+  // `constElem`, returning true iff `elem` was modified, i.e. if it was not
+  // already an upper bound of `constElem`.
   { lattice.join(elem, constElem) } noexcept -> std::same_as<bool>;
 };
 

src/analysis/lattices/powerset.h

@@ -85,9 +85,9 @@ class FiniteIntPowersetLattice {
   // Returns an instance of the bottom lattice element.
   Element getBottom() const noexcept;
 
-  // Calculates the LUB of this element with some other element and sets
-  // this element to the LUB in place. Returns true if this element before
-  // this method call was different than the LUB.
+  // Modifies `self` to be the join (aka least upper bound) of `self` and
+  // `other`. Returns true if `self` was modified, i.e. if it was not already an
+  // upper bound of `other`.
   bool join(Element& self, const Element& other) const noexcept;
 };