[docs] Update DominatorTree docs to clarify expectations around unreachable blocks

[reames]

Summary

Note: I'm am not trying to describe what "should be"; I'm only describing what is true today.

The text has been discussed offline with DannyB, but I wanted to a) give him a final chance to comment and b) make sure others were okay with the proposed wording.

This came out of my recent question to llvm-dev titled: When can the dominator tree not contain a node for a basic block?

[JosephTremoulet]

lgtm aside from a typo

include/llvm/Support/GenericDomTree.h

375 ↗

(On Diff #35438)

typo: s/an/a/

[• dberlin]

It's closed, but just FYI, it looked fine to me, so i never hit respond.

llvm/trunk/include/llvm/IR/Dominators.h

public:
   const BasicBlock *getEnd() const {
     return End;
   }
   bool isSingleEdge() const;
 };
 
 /// \brief Concrete subclass of DominatorTreeBase that is used to compute a
 /// normal dominator tree.
+///
+/// Definition: A block is said to be forward statically reachable if there is
+/// a path from the entry of the function to the block.  A statically reachable
+/// block may become statically unreachable during optimization.
+///
+/// A forward unreachable block may appear in the dominator tree, or it may
+/// not.  If it does, dominance queries will return results as if all reachable
+/// blocks dominate it.  When asking for a Node corresponding to a potentially
+/// unreachable block, calling code must handle the case where the block was
+/// unreachable and the result of getNode() is nullptr.
+///
+/// Generally, a block known to be unreachable when the dominator tree is
+/// constructed will not be in the tree.  One which becomes unreachable after
+/// the dominator tree is initially constructed may still exist in the tree,
+/// even if the tree is properly updated. Calling code should not rely on the
+/// preceding statements; this is stated only to assist human understanding.
 class DominatorTree : public DominatorTreeBase<BasicBlock> {
 public:
   typedef DominatorTreeBase<BasicBlock> Base;
 
   DominatorTree() : DominatorTreeBase<BasicBlock>(false) {}
   explicit DominatorTree(Function &F) : DominatorTreeBase<BasicBlock>(false) {
     recalculate(F);
   }

llvm/trunk/include/llvm/Support/GenericDomTree.h

bool compare(const DominatorTreeBase &Other) const {
     }
 
     return false;
   }
 
   void releaseMemory() { reset(); }
 
   /// getNode - return the (Post)DominatorTree node for the specified basic
-  /// block.  This is the same as using operator[] on this class.
-  ///
+  /// block.  This is the same as using operator[] on this class.  The result
+  /// may (but is not required to) be null for a forward (backwards)
+  /// statically unreachable block.
   DomTreeNodeBase<NodeT> *getNode(NodeT *BB) const {
     auto I = DomTreeNodes.find(BB);
     if (I != DomTreeNodes.end())
       return I->second.get();
     return nullptr;
   }
 
+  /// See getNode.
   DomTreeNodeBase<NodeT> *operator[](NodeT *BB) const { return getNode(BB); }
 
   /// getRootNode - This returns the entry node for the CFG of the function.  If
   /// this tree represents the post-dominance relations for a function, however,
   /// this root may be a node with the block == NULL.  This is the case when
   /// there are multiple exit nodes from a particular function.  Consumers of
   /// post-dominance information must be capable of dealing with this
   /// possibility.