Java/Shared: Address review comments.

Author: aschackmull

java/ql/lib/change-notes/2025-05-16-shared-basicblocks.md

@@ -1,4 +1,4 @@
 ---
 category: deprecated
 ---
-* Java now uses the shared `BasicBlock` library. This means that several member predicates now use the preferred names. The old predicates have been deprecated. The `BasicBlock` class itself no longer extends `ControlFlowNode` - the predicate `getFirstNode` can be used to fix any QL code that somehow relied on this.
+* Java now uses the shared `BasicBlock` library. This means that the names of several member predicates have been changed to align with the names used in other languages. The old predicates have been deprecated. The `BasicBlock` class itself no longer extends `ControlFlowNode` - the predicate `getFirstNode` can be used to fix any QL code that somehow relied on this.

java/ql/lib/semmle/code/java/controlflow/BasicBlocks.qll

@@ -70,10 +70,8 @@ predicate hasDominanceInformation(BasicBlock bb) {
 }
 
 /**
- * A control-flow node that represents the start of a basic block.
- *
- * A basic block is a series of nodes with no control-flow branching, which can
- * often be treated as a unit in analyses.
+ * A basic block, that is, a maximal straight-line sequence of control flow nodes
+ * without branches or joins.
  */
 class BasicBlock extends BbImpl::BasicBlock {
   /** Gets the immediately enclosing callable whose body contains this node. */

shared/controlflow/codeql/controlflow/BasicBlock.qll

@@ -246,9 +246,9 @@ module Make<LocationSig Location, InputSig<Location> Input> {
    * implies that `(bb1, bb2)` dominates its endpoint `bb2`. I.e., `bb2` can
    * only be reached from the entry block by going via `(bb1, bb2)`.
    *
-   * This is a necessary and sufficient condition for an edge to dominate anything,
-   * and in particular `dominatingEdge(bb1, bb2) and bb2.dominates(bb3)` means
-   * that the edge `(bb1, bb2)` dominates `bb3`.
+   * This is a necessary and sufficient condition for an edge to dominate some
+   * block, and therefore `dominatingEdge(bb1, bb2) and bb2.dominates(bb3)`
+   * means that the edge `(bb1, bb2)` dominates `bb3`.
    */
   pragma[nomagic]
   predicate dominatingEdge(BasicBlock bb1, BasicBlock bb2) {