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

[Florian Mayer via cfe-commits]

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

None

>From 090f5a27ddf116a00b5d009ea37e8557db820e39 Mon Sep 17 00:00:00 2001
From: Florian Mayer <fmayer at google.com>
Date: Mon, 9 Feb 2026 17:55:48 -0800
Subject: [PATCH] =?UTF-8?q?[=F0=9D=98=80=F0=9D=97=BD=F0=9D=97=BF]=20initia?=
 =?UTF-8?q?l=20version?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created using spr 1.3.7
---
 .../abseil/unchecked-statusor-access.rst      | 42 ++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

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
 -------------------------------------------------------------------------------