[clang-tools-extra] [NFC] [clang-tidy] [doc] document gtest support of statusor check (PR #180662)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tools-extra

@llvm/pr-subscribers-clang-tidy

Author: Florian Mayer (fmayer)

<details>
<summary>Changes</summary>



---
Full diff: https://github.com/llvm/llvm-project/pull/180662.diff


1 Files Affected:

- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.rst (+41-1) 


``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.rst b/clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.rst
index 7aef674724b08..bd1054ce68415 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.rst
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.rst
@@ -93,7 +93,7 @@ known to have ok status. For example:
 Ensuring that the status is ok using common macros
 --------------------------------------------------
 
-The check is aware of common macros like ``ABSL_CHECK`` and ``ASSERT_THAT``.
+The check is aware of common macros like ``ABSL_CHECK`` or ``ABSL_CHECK_OK``,
 Those can be used to ensure that the status of a ``StatusOr<T>`` object
 is ok. For example:
 
@@ -104,6 +104,46 @@ is ok. For example:
      use(*x);
    }
 
+Ensuring that the status is ok using googletest macros
+------------------------------------------------------
+
+The check is aware of ``googletest`` (or ``gtest``) macros and matchers.
+Accessing the value of a ``StatusOr<T>`` object is considered safe if it
+is preceded by an ``ASSERT_`` macro that ensures the status is ok.
+For example
+
+.. code:: cpp
+
+   TEST(MySuite, MyTest) {
+     absl::StatusOr<int> x = foo();
+     ASSERT_OK(x);
+     use(*x);
+   }
+
+   TEST(MySuite, MyOtherTest) {
+     absl::StatusOr<int> x = foo();
+     ASSERT_THAT(x, absl_testing::IsOk());
+     use(*x);
+   }
+
+The following ``googletest`` macros are supported:
+
+- ``ASSERT_OK(...)``
+- ``ASSERT_TRUE(...)``
+- ``ASSERT_FALSE(...)``
+- ``ASSERT_THAT(...)``
+
+The following matchers are supported:
+
+- ``IsOk()``
+- ``StatusIs(...)``
+- ``IsOkAndHolds(...)``
+- ``CanonicalStatusIs(...)``
+
+**Note**: ``EXPECT_`` macros (like ``EXPECT_OK`` or ``EXPECT_TRUE(x.ok())``)
+do **not** make subsequent accesses safe because they do not terminate the
+test execution.
+
 Ensuring that the status is ok, then accessing the value in a correlated branch
 -------------------------------------------------------------------------------
 

``````````

</details>


https://github.com/llvm/llvm-project/pull/180662