Add documentation

include/clad/Differentiator/TBRAnalyzer.h

@@ -14,6 +14,14 @@ using namespace clang;
 
 namespace clad {
 
+/// Gradient computation requres reversal of the control flow of the original
+/// program becomes necessary. To guarantee correctness, certain values that are
+/// computed and overwritten in the original program must be made available in
+/// the adjoint program. They can be determined by performing a static data flow
+/// analysis, the so-called To-Be-Recorded (TBR) analysis. Overestimation of
+/// this set must be kept minimal to get efficient adjoint codes.
+///
+/// This class implements this to-be-recorded analysis.
 class TBRAnalyzer : public clang::RecursiveASTVisitor<TBRAnalyzer> {
   /// ProfileID is the key type for ArrMap used to represent array indices
   /// and object fields.
@@ -37,22 +45,23 @@ class TBRAnalyzer : public clang::RecursiveASTVisitor<TBRAnalyzer> {
     }
   };
 
+
+  struct VarData;
+  using ArrMap =
+      std::unordered_map<const ProfileID, VarData, ProfileIDHash>;
+
+  // NOLINTBEGIN(cppcoreguidelines-pro-type-union-access)
+
   /// Stores all the necessary information about one variable. Fundamental type
   /// variables need only one bit. An object/array needs a separate VarData for
   /// each field/element. Reference type variables store the clang::Expr* they
   /// refer to. UNDEFINED is used whenever the type of a node cannot be determined.
-
+  ///
   /// FIXME: Pointers to objects are considered OBJ_TYPE for simplicity. This
   /// approach might cause problems when the support for pointers is added.
-
+  ///
   /// FIXME: Add support for references to call expression results.
   /// 'double& x = f(b);' is not supported.
-
-  struct VarData;
-  using ArrMap =
-      std::unordered_map<const ProfileID, VarData, ProfileIDHash>;
-
-  // NOLINTBEGIN(cppcoreguidelines-pro-type-union-access)
   struct VarData {
     enum VarDataType { UNDEFINED, FUND_TYPE, OBJ_TYPE, ARR_TYPE, REF_TYPE };
     union VarDataValue {