[clang-tidy][NFC] Improve doc of cppcoreguidelines-misleading-capture-default-by-value

Also fix ordering in Release Notes.

Differential Revision: https://reviews.llvm.org/D148424

Author: carlosgalvezp

clang-tools-extra/clang-tidy/cppcoreguidelines/MisleadingCaptureDefaultByValueCheck.h

@@ -16,11 +16,8 @@ namespace clang::tidy::cppcoreguidelines {
 
 /// Warns when lambda specify a by-value capture default and capture ``this``.
 ///
-/// By-value capture defaults in lambas defined within member functions can be
-/// misleading about whether capturing data member is by value or reference.
-/// For example, [=] will capture local variables by value but member variables
-/// by reference. CppCoreGuideline F.54 suggests to never use by-value capture
-/// default when capturing this.
+/// By-value capture defaults in member functions can be misleading about
+/// whether data members are captured by value or reference.
 ///
 /// For the user-facing documentation see:
 /// http://clang.llvm.org/extra/clang-tidy/checks/cppcoreguidelines/misleading-capture-default-by-value.html

clang-tools-extra/docs/ReleaseNotes.rst

@@ -112,18 +112,18 @@ New checks
   This check relies heavily on, but is not exclusive to, the functions from
   the *Annex K. "Bounds-checking interfaces"* of C11.
 
-- New :doc:`cppcoreguidelines-misleading-capture-default-by-value
-  <clang-tidy/checks/cppcoreguidelines/misleading-capture-default-by-value>` check.
-
-  Warns when lambda specify a by-value capture default and capture ``this``.
-
 - New :doc:`cppcoreguidelines-avoid-capturing-lambda-coroutines
   <clang-tidy/checks/cppcoreguidelines/avoid-capturing-lambda-coroutines>` check.
 
   Flags C++20 coroutine lambdas with non-empty capture lists that may cause
   use-after-free errors and suggests avoiding captures or ensuring the lambda
   closure object has a guaranteed lifetime.
 
+- New :doc:`cppcoreguidelines-misleading-capture-default-by-value
+  <clang-tidy/checks/cppcoreguidelines/misleading-capture-default-by-value>` check.
+
+  Warns when lambda specify a by-value capture default and capture ``this``.
+
 - New :doc:`cppcoreguidelines-rvalue-reference-param-not-moved
   <clang-tidy/checks/cppcoreguidelines/rvalue-reference-param-not-moved>` check.
 

clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/misleading-capture-default-by-value.rst

@@ -5,10 +5,14 @@ cppcoreguidelines-misleading-capture-default-by-value
 
 Warns when lambda specify a by-value capture default and capture ``this``.
 
-By-value capture-defaults in member functions can be misleading about
-whether data members are captured by value or reference. For example,
-specifying the capture default ``[=]`` will still capture data members
-by reference.
+By-value capture defaults in member functions can be misleading about whether
+data members are captured by value or reference. This occurs because specifying
+the capture default ``[=]`` actually captures the ``this`` pointer by value,
+not the data members themselves. As a result, data members are still indirectly
+accessed via the captured ``this`` pointer, which essentially means they are
+being accessed by reference. Therefore, even when using ``[=]``, data members
+are effectively captured by reference, which might not align with the user's
+expectations.
 
 Examples: