Documentation: Update docs for C++ lambdas to more accurately reflect

C++1y init-capture support, and to improve some Doxygen markup.


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@185469 91177308-0d34-0410-b5e6-96231b3b80d8

2 files changed, 28 insertions, 17 deletions

diff --git a/include/clang/AST/ExprCXX.h b/include/clang/AST/ExprCXX.h
index 2b961d6291..a241d1eded 100644
--- a/include/clang/AST/ExprCXX.h
+++ b/include/clang/AST/ExprCXX.h
@@ -1283,12 +1283,16 @@ public:
 /// }
 /// \endcode
 ///
-/// Lambda expressions can capture local variables, either by copying
+/// C++11 lambda expressions can capture local variables, either by copying
 /// the values of those local variables at the time the function
 /// object is constructed (not when it is called!) or by holding a
 /// reference to the local variable. These captures can occur either
 /// implicitly or can be written explicitly between the square
 /// brackets ([...]) that start the lambda expression.
+///
+/// C++1y introduces a new form of "capture" called an init-capture that
+/// includes an initializing expression (rather than capturing a variable),
+/// and which can never occur implicitly.
 class LambdaExpr : public Expr {
   enum {
     /// \brief Flag used by the Capture class to indicate that the given
@@ -1297,6 +1301,8 @@ class LambdaExpr : public Expr {
 
     /// \brief Flag used by the Capture class to indicate that the
     /// given capture was by-copy.
+    ///
+    /// This includes the case of a non-reference init-capture.
     Capture_ByCopy = 0x02
   };
 
@@ -1336,7 +1342,8 @@ class LambdaExpr : public Expr {
   // array captures.
 
 public:
-  /// \brief Describes the capture of either a variable or 'this'.
+  /// \brief Describes the capture of a variable or of \c this, or of a
+  /// C++1y init-capture.
   class Capture {
     llvm::PointerIntPair<Decl *, 2> DeclAndBits;
     SourceLocation Loc;
@@ -1346,16 +1353,17 @@ public:
     friend class ASTStmtWriter;
     
   public:
-    /// \brief Create a new capture.
+    /// \brief Create a new capture of a variable or of \c this.
     ///
     /// \param Loc The source location associated with this capture.
     ///
-    /// \param Kind The kind of capture (this, byref, bycopy).
+    /// \param Kind The kind of capture (this, byref, bycopy), which must
+    /// not be init-capture.
     ///
     /// \param Implicit Whether the capture was implicit or explicit.
     ///
-    /// \param Var The local variable being captured, or null if capturing this
-    ///        or if this is an init-capture.
+    /// \param Var The local variable being captured, or null if capturing
+    /// \c this.
     ///
     /// \param EllipsisLoc The location of the ellipsis (...) for a
     /// capture that is a pack expansion, or an invalid source
@@ -1370,7 +1378,7 @@ public:
     /// \brief Determine the kind of capture.
     LambdaCaptureKind getCaptureKind() const;
 
-    /// \brief Determine whether this capture handles the C++ 'this'
+    /// \brief Determine whether this capture handles the C++ \c this
     /// pointer.
     bool capturesThis() const { return DeclAndBits.getPointer() == 0; }
 
@@ -1379,14 +1387,14 @@ public:
       return dyn_cast_or_null<VarDecl>(DeclAndBits.getPointer());
     }
 
-    /// \brief Determines whether this is an init-capture.
+    /// \brief Determine whether this is an init-capture.
     bool isInitCapture() const { return getCaptureKind() == LCK_Init; }
 
     /// \brief Retrieve the declaration of the local variable being
     /// captured.
     ///
     /// This operation is only valid if this capture is a variable capture
-    /// (other than a capture of 'this').
+    /// (other than a capture of \c this).
     VarDecl *getCapturedVar() const {
       assert(capturesVariable() && "No variable available for 'this' capture");
       return cast<VarDecl>(DeclAndBits.getPointer());
@@ -1410,7 +1418,7 @@ public:
     ///
     /// For an explicit capture, this returns the location of the
     /// explicit capture in the source. For an implicit capture, this
-    /// returns the location at which the variable or 'this' was first
+    /// returns the location at which the variable or \c this was first
     /// used.
     SourceLocation getLocation() const { return Loc; }
 
diff --git a/include/clang/Basic/Lambda.h b/include/clang/Basic/Lambda.h
index 48f5229dc6..29ecb3a167 100644
--- a/include/clang/Basic/Lambda.h
+++ b/include/clang/Basic/Lambda.h
@@ -8,7 +8,7 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief  Defines several types used to describe C++ lambda expressions
+/// \brief Defines several types used to describe C++ lambda expressions
 /// that are shared between the parser and AST.
 ///
 //===----------------------------------------------------------------------===//
@@ -26,13 +26,16 @@ enum LambdaCaptureDefault {
   LCD_ByRef
 };
 
-/// \brief The different capture forms in a lambda introducer: 'this' or a
-/// copied or referenced variable.
+/// \brief The different capture forms in a lambda introducer
+///
+/// C++11 allows capture of \c this, or of local variables by copy or
+/// by reference.  C++1y also allows "init-capture", where the initializer
+/// is an expression.
 enum LambdaCaptureKind {
-  LCK_This,
-  LCK_ByCopy,
-  LCK_ByRef,
-  LCK_Init
+  LCK_This,   ///< Capturing the \c this pointer
+  LCK_ByCopy, ///< Capturing by copy (a.k.a., by value)
+  LCK_ByRef,  ///< Capturing by reference
+  LCK_Init    ///< C++1y "init-capture", value specified by an expression
 };
 
 } // end namespace clang