[clang-tidy] Clarify documention of `bugprone-unchecked-optional-access`.

[ymandel]

Summary

Removes a reference to google-internal document and expands the relevant material in place.

Fixes #60633.

[xazax.hun]

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

278

Strictly speaking, value on an empty optional will not terminate the program. It will raise an exception that can be handled.

(Of course, at Google, exceptions are banned so termination is right in that context.)

[ymandel]

address comments

[ymandel]

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

278

Right! Updated to mention both possibilities. Thx

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

 .. title:: clang-tidy - bugprone-unchecked-optional-access
 
 bugprone-unchecked-optional-access
 ==================================
 
 *Note*: This check uses a flow-sensitive static analysis to produce its
 results. Therefore, it may be more resource intensive (RAM, CPU) than the
 average clang-tidy check.
 
 This check identifies unsafe accesses to values contained in
-``std::optional<T>``, ``absl::optional<T>``, or ``base::std::optional<T>``
-objects. Below we will refer to all these types collectively as
-``optional<T>``.
-
-An access to the value of an ``optional<T>`` occurs when one of its
-``value``, ``operator*``, or ``operator->`` member functions is invoked.
-To align with common misconceptions, the check considers these member
-functions as equivalent, even though there are subtle differences
-related to exceptions versus undefined behavior. See
-go/optional-style-recommendations for more information on that topic.
+``std::optional<T>``, ``absl::optional<T>``, or ``base::Optional<T>``
+objects. Below we will refer to all these types collectively as ``optional<T>``.
+
+An access to the value of an ``optional<T>`` occurs when one of its ``value``,
+``operator*``, or ``operator->`` member functions is invoked.  To align with
+common misconceptions, the check considers these member functions as equivalent,
+even though there are subtle differences related to exceptions versus undefined
+behavior. See *Additional notes*, below, for more information on this topic.
 
 An access to the value of an ``optional<T>`` is considered safe if and only if
 code in the local scope (for example, a function body) ensures that the
 ``optional<T>`` has a value in all possible execution paths that can reach the
 access. That should happen either through an explicit check, using the
 ``optional<T>::has_value`` member function, or by constructing the
 ``optional<T>`` in a way that shows that it unambiguously holds a value (e.g
 using ``std::make_optional`` which always returns a populated

 
 Lambdas
 -------
 
 The check does not currently report unsafe optional accesses in lambdas.
 A future version will expand the scope to lambdas, following the rules
 outlined above. It is best to follow the same principles when using
 optionals in lambdas.
+
+Access with ``operator*()`` vs. ``value()``
+-------------------------------------------
+
+Given that ``value()`` has well-defined behavior (either throwing an exception
+or terminating the program), why treat it the same as ``operator*()`` which
+causes undefined behavior (UB)? That is, why is it considered unsafe to access
+an optional with ``value()``, if it's not provably populated with a value?  For
+that matter, why is ``CHECK()`` followed by ``operator*()`` any better than
+``value()``, given that they are semantically equivalent (on configurations that
+disable exceptions)?
+
+The answer is that we assume most users do not realize the difference between
+``value()`` and ``operator*()``. Shifting to ``operator*()`` and some form of
+explicit value-presence check or explicit program termination has two
+advantages:
+
+  * Readability. The check, and any potential side effects like program
+    shutdown, are very clear in the code. Separating access from checks can
+    actually make the checks more obvious.
+
+  * Performance. A single check can cover many or even all accesses within
+    scope. This gives the user the best of both worlds -- the safety of a
+    dynamic check, but without incurring redundant costs.