Documentation improvements

Author: Sirraide

clang/include/clang/AST/Decl.h

@@ -1247,7 +1247,7 @@ class VarDecl : public DeclaratorDecl, public Redeclarable<VarDecl> {
 
   /// Returns true for local variable declarations other than parameters.
   /// Note that this includes static variables inside of functions. It also
-  /// includes variables inside blocks.
+  /// includes variables inside blocks and expansion statements.
   ///
   ///   void foo() { int x; static int y; extern int z; }
   bool isLocalVarDecl() const {

clang/include/clang/AST/DeclTemplate.h

@@ -3375,7 +3375,18 @@ class TemplateParamObjectDecl : public ValueDecl,
 /// 'CXXExpansionStmtInstantiation' is. The latter is also what's used for
 /// codegen and constant evaluation.
 ///
-/// For example, if the user writes the following expansion statement:
+/// There are three kinds of expansion statements; they correspond to three
+/// derived classes of 'CXXExpansionStmtPattern'. There is also a fourth derived
+/// class that is used if we don't know what kind of expansion statement we're
+/// dealing with (because the thing we're expanding is dependent). See the
+/// comment on those classes for more information about how they work:
+///
+///   1. CXXEnumeratingExpansionStmtPattern
+///   2. CXXIteratingExpansionStmtPattern
+///   3. CXXDestructuringExpansionStmtPattern
+///   4. CXXDependentExpansionStmtPattern
+///
+/// As an example, if the user writes the following expansion statement:
 /// \verbatim
 ///   std::tuple<int, int, int> a{1, 2, 3};
 ///   template for (auto x : a) {
@@ -3389,28 +3400,33 @@ class TemplateParamObjectDecl : public ValueDecl,
 /// 'a'.
 ///
 /// After expansion, we end up with a 'CXXExpansionStmtInstantiation' that
-/// contains a DecompositionDecl and 3 CompoundStmts, one for each expansion:
+/// is *equivalent* to the AST shown below. Note that only the inner '{}' (i.e.
+/// those marked as 'Actual "CompoundStmt"' below) are actually present as
+/// 'CompoundStmt's in the AST; the outer braces that wrap everything do *not*
+/// correspond to an actual 'CompoundStmt' and are implicit in the sense that we
+/// simply push a scope when evaluating or emitting IR for a
+/// 'CXXExpansionStmtInstantiation'.
 ///
 /// \verbatim
-/// {
+/// { // Not actually present in the AST.
 ///   auto [__u0, __u1, __u2] = a;
-///   {
+///   { // Actual 'CompoundStmt'.
 ///     auto x = __u0;
 ///     // ...
 ///   }
-///   {
+///   { // Actual 'CompoundStmt'.
 ///     auto x = __u1;
 ///     // ...
 ///   }
-///   {
+///   { // Actual 'CompoundStmt'.
 ///     auto x = __u2;
 ///     // ...
 ///   }
 /// }
 /// \endverbatim
 ///
-/// The outer braces shown above are implicit; we don't actually create another
-/// CompoundStmt wrapping everything.
+/// See the documentation around 'CXXExpansionStmtInstantiation' for more notes
+/// as to why this node exist and how it is used.
 ///
 /// \see CXXExpansionStmtPattern
 /// \see CXXExpansionStmtInstantiation

clang/include/clang/AST/ExprCXX.h

@@ -5501,6 +5501,19 @@ class BuiltinBitCastExpr final
 
 /// Represents an expansion-init-list of an enumerating expansion statement.
 ///
+/// For example, in
+/// \verbatim
+///   template for (auto x : { 1, 2, 3 }) {
+///     // ...
+///   }
+/// \endverbatim
+///
+/// the '{ 1, 2, 3 }' part is parsed and stored as a 'CXXExpansionInitListExpr';
+/// syntactically, this *looks* very similar to an initializer list, but it
+/// isn't actually an expression: '{ 1, 2, 3 }' as a whole is never evaluated
+/// or emitted, only the individual expressions '1', '2', and '3' are. We still
+/// represent it as an expression in the AST for simplicity.
+///
 /// \see CXXEnumeratingExpansionStmtPattern
 class CXXExpansionInitListExpr final
     : public Expr,

clang/include/clang/AST/StmtCXX.h

@@ -533,11 +533,7 @@ class CoreturnStmt : public Stmt {
 /// subexpressions required by its derived classes. This is to simplify the
 /// implementation of 'children()' and friends.
 ///
-/// \see CXXExpansionStmtDecl
-/// \see CXXEnumeratingExpansionStmtPattern
-/// \see CXXIteratingExpansionStmtPattern
-/// \see CXXDestructuringExpansionStmtPattern
-/// \see CXXDependentExpansionStmtPattern
+/// \see CXXExpansionStmtDecl for more documentation on expansion statements.
 class CXXExpansionStmtPattern : public Stmt {
   friend class ASTStmtReader;
 
@@ -878,25 +874,28 @@ class CXXDestructuringExpansionStmtPattern : public CXXExpansionStmtPattern {
 /// Represents the code generated for an expanded expansion statement.
 ///
 /// This holds 'shared statements' and 'instantiations'; these encode the
-/// general underlying pattern that all expansion statements desugar to:
+/// general underlying pattern that all expansion statements desugar to. Note
+/// that only the inner '{}' (i.e. those marked as 'Actual "CompoundStmt"'
+/// below) are actually present as 'CompoundStmt's in the AST; the outer braces
+/// that wrap everything do *not* correspond to an actual 'CompoundStmt' and are
+/// implicit in the sense that we simply push a scope when evaluating or
+/// emitting IR for a 'CXXExpansionStmtInstantiation'.
+///
+/// The 'instantiations' are precisely these inner compound statements.
 ///
 /// \verbatim
-/// {
+/// { // Not actually present in the AST.
 ///   <shared statements>
-///   {
+///   { // Actual 'CompoundStmt'.
 ///     <1st instantiation>
 ///   }
 ///   ...
-///   {
+///   { // Actual 'CompoundStmt'.
 ///     <n-th instantiation>
 ///   }
 /// }
 /// \endverbatim
 ///
-/// Here, the only thing that is stored in the AST are the 'shared statements'
-/// and the 'CompoundStmt's that wrap the 'instantiations'. The outer braces
-/// shown above are implicit.
-///
 /// For example, the CXXExpansionStmtInstantiation that corresponds to the
 /// following expansion statement
 ///
@@ -926,6 +925,19 @@ class CXXDestructuringExpansionStmtPattern : public CXXExpansionStmtPattern {
 ///   }
 /// }
 /// \endverbatim
+///
+/// There are two reasons why this needs to exist and why we don't just store a
+/// list of instantiations in some other node:
+///
+///   1. We need custom codegen to handle break/continue in expansion statements
+///      properly, so it can't just be a compound statement.
+///
+///   2. The expansions are created after both the pattern and the
+///      'CXXExpansionStmtDecl', so we can't just store them as trailing data in
+///      either of those nodes (because we don't know how many expansions there
+///      will be when those notes are allocated).
+///
+/// \see CXXExpansionStmtDecl
 class CXXExpansionStmtInstantiation final
     : public Stmt,
       llvm::TrailingObjects<CXXExpansionStmtInstantiation, Stmt *> {