[analyzer] Enhance docs for checker callbacks (esp. processRegionChanges).

No functionality change; this checker is only used for documentation.

llvm-svn: 167522

diff --git a/clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp b/clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp
index 58ada9d..efaec2b 100644 (file)
--- a/clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp
+++ b/clang/lib/StaticAnalyzer/Checkers/CheckerDocumentation.cpp
@@ -25,6 +25,7 @@ using namespace ento;
 // All checkers should be placed into anonymous namespace.
 // We place the CheckerDocumentation inside ento namespace to make the
 // it visible in doxygen.
+namespace clang {
 namespace ento {
 
 /// This checker documents the callback functions checkers can use to implement
@@ -151,9 +152,8 @@ public:
   /// check::DeadSymbols
   void checkDeadSymbols(SymbolReaper &SR, CheckerContext &C) const {}
 
-  /// \brief Called when an end of path is reached in the ExplodedGraph.
-  ///
-  /// This callback should be used to check if the allocated resources are freed.
+  /// \brief Called when the analyzer core reaches the end of the top-level
+  /// function being analyzed.
   ///
   /// check::EndPath
   void checkEndPath(CheckerContext &Ctx) const {}
@@ -213,21 +213,35 @@ public:
   /// check::LiveSymbols
   void checkLiveSymbols(ProgramStateRef State, SymbolReaper &SR) const {}
 
-
+  /// \brief Called to determine if the checker currently needs to know if when
+  /// contents of any regions change.
+  ///
+  /// Since it is not necessarily cheap to compute which regions are being
+  /// changed, this allows the analyzer core to skip the more expensive
+  /// #checkRegionChanges when no checkers are tracking any state.
   bool wantsRegionChangeUpdate(ProgramStateRef St) const { return true; }
   
-  /// \brief Allows tracking regions which get invalidated.
+  /// \brief Called when the contents of one or more regions change.
+  ///
+  /// This can occur in many different ways: an explicit bind, a blanket
+  /// invalidation of the region contents, or by passing a region to a function
+  /// call whose behavior the analyzer cannot model perfectly.
   ///
   /// \param State The current program state.
   /// \param Invalidated A set of all symbols potentially touched by the change.
   /// \param ExplicitRegions The regions explicitly requested for invalidation.
-  ///   For example, in the case of a function call, these would be arguments.
-  /// \param Regions The transitive closure of accessible regions,
-  ///   i.e. all regions that may have been touched by this change.
-  /// \param Call The call expression wrapper if the regions are invalidated
-  ///   by a call, 0 otherwise.
-  /// Note, in order to be notified, the checker should also implement the
-  /// wantsRegionChangeUpdate callback.
+  ///        For a function call, this would be the arguments. For a bind, this
+  ///        would be the region being bound to.
+  /// \param Regions The transitive closure of regions accessible from,
+  ///        \p ExplicitRegions, i.e. all regions that may have been touched
+  ///        by this change. For a simple bind, this list will be the same as
+  ///        \p ExplicitRegions, since a bind does not affect the contents of
+  ///        anything accessible through the base region.
+  /// \param Call The opaque call triggering this invalidation. Will be 0 if the
+  ///        change was not triggered by a call.
+  ///
+  /// Note that this callback will not be invoked unless
+  /// #wantsRegionChangeUpdate returns \c true.
   ///
   /// check::RegionChanges
   ProgramStateRef 
@@ -261,4 +275,5 @@ void CheckerDocumentation::checkPostStmt(const DeclStmt *DS,
   return;
 }
 
-} // end namespace
+} // end namespace ento
+} // end namespace clang