[clang-tidy] Add a release note about unchecked-optional-access smart pointer caching

clang-tools-extra/docs/ReleaseNotes.rst

@@ -108,6 +108,12 @@ Changes in existing checks
   calls of ``std::string`` constructor with char pointer, start position and
   length parameters.
 
+- Improved :doc:`bugprone-unchecked-optional-access
+  <clang-tidy/checks/bugprone/unchecked-optional-access>` fixing false
+  positives from smart pointer accessors repeated in checking ``has_value``
+  and accessing ``value``. The option `IgnoreSmartPointerDereference` should
+  no longer be needed and will be removed.
+
 - Improved :doc:`bugprone-unsafe-functions
   <clang-tidy/checks/bugprone/unsafe-functions>` check to allow specifying
   additional C++ member functions to match.

clang-tools-extra/docs/clang-tidy/checks/bugprone/unchecked-optional-access.rst

@@ -71,8 +71,8 @@ For example:
 .. code-block:: c++
 
    void f(Foo foo) {
-     if (foo.opt().has_value()) {
-       use(*foo.opt()); // unsafe: it is unclear whether `foo.opt()` has a value.
+     if (foo.take().has_value()) {
+       use(*foo.take()); // unsafe: it is unclear whether `foo.take()` has a value.
      }
    }
 
@@ -81,10 +81,11 @@ Exception: accessor methods
 
 The check assumes *accessor* methods of a class are stable, with a heuristic to
 determine which methods are accessors. Specifically, parameter-free ``const``
-methods are treated as accessors. Note that this is not guaranteed to be safe
--- but, it is widely used (safely) in practice, and so we have chosen to treat
-it as generally safe. Calls to non ``const`` methods are assumed to modify
-the state of the object and affect the stability of earlier accessor calls.
+methods and smart pointer-like APIs (non ``const`` overloads of ``*`` when
+there is a parallel ``const`` overload) are treated as accessors. Note that
+this is not guaranteed to be safe -- but, it is widely used (safely) in
+practice. Calls to non ``const`` methods are assumed to modify the state of
+the object and affect the stability of earlier accessor calls.
 
 Rely on invariants of uncommon APIs
 -----------------------------------
@@ -191,14 +192,15 @@ paths that lead to an access. For example:
 Stabilize function results
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Since function results are not assumed to be stable across calls, it is best to
-store the result of the function call in a local variable and use that variable
-to access the value. For example:
+Function results are not assumed to be stable across calls, except for
+const accessor methods. For more complex accessors (non-const, or depend on
+multiple params) it is best to store the result of the function call in a
+local variable and use that variable to access the value. For example:
 
 .. code-block:: c++
 
    void f(Foo foo) {
-     if (const auto& foo_opt = foo.opt(); foo_opt.has_value()) {
+     if (const auto& foo_opt = foo.take(); foo_opt.has_value()) {
        use(*foo_opt);
      }
    }