[CaptureTracking][NFC] Clarify usage expectations in PointerMayBeCaptured comments (llvm#132744)

Fixes issue llvm#132739.

CaptureAnalysis only considers captures through the def-use chain of the
provided pointer, explicitly excluding captures of underlying values or
implicit captures like those involving external globals.

The previous comment for `PointerMayBeCaptured` did not clearly state
this limitation, leading to its incorrect usage in files such as
ThreadSanitizer.cpp and SanitizerMetadata.cpp.

This PR addresses this by refining the comments for the relevant APIs
within `PointerMayBeCaptured` to explicitly document this behavior.

Author: Camsyn

llvm/include/llvm/Analysis/CaptureTracking.h

@@ -41,13 +41,19 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   bool PointerMayBeCaptured(const Value *V, bool ReturnCaptures,
                             unsigned MaxUsesToExplore = 0);
 
   /// Return which components of the pointer may be captured. Only consider
   /// components that are part of \p Mask. Once \p StopFn on the accumulated
   /// components returns true, the traversal is aborted early. By default, this
   /// happens when *any* of the components in \p Mask are captured.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   CaptureComponents PointerMayBeCaptured(
       const Value *V, bool ReturnCaptures, CaptureComponents Mask,
       function_ref<bool(CaptureComponents)> StopFn = capturesAnything,
@@ -64,6 +70,9 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   bool PointerMayBeCapturedBefore(const Value *V, bool ReturnCaptures,
                                   const Instruction *I, const DominatorTree *DT,
                                   bool IncludeI = false,
@@ -75,6 +84,9 @@ namespace llvm {
   /// on the accumulated components returns true, the traversal is aborted
   /// early. By default, this happens when *any* of the components in \p Mask
   /// are captured.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   CaptureComponents PointerMayBeCapturedBefore(
       const Value *V, bool ReturnCaptures, const Instruction *I,
       const DominatorTree *DT, bool IncludeI, CaptureComponents Mask,
@@ -184,6 +196,9 @@ namespace llvm {
   /// MaxUsesToExplore specifies how many uses the analysis should explore for
   /// one value before giving up due too "too many uses". If MaxUsesToExplore
   /// is zero, a default value is assumed.
+  /// This function only considers captures of the passed value via its def-use
+  /// chain, without considering captures of values it may be based on, or
+  /// implicit captures such as for external globals.
   void PointerMayBeCaptured(const Value *V, CaptureTracker *Tracker,
                             unsigned MaxUsesToExplore = 0);