From c4ed56eb75b1c1f9d1fc7e98f8c9724bb73e2442 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Kr=C3=A4mer?= <sebkraemer@posteo.org>
Date: Tue, 15 Dec 2020 21:24:41 +0100
Subject: [PATCH 1/3] Add subsection for GTEST_SKIP documentation

A subsection "Skipping test execution" was added to document GTEST_SKIP
and where it can be used.

relates issue #1544
---
 docs/advanced.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/advanced.md b/docs/advanced.md
index ae4d7ee8..da7cf079 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -527,6 +527,32 @@ destructor early, possibly leaving your object in a partially-constructed or
 partially-destructed state! You almost certainly want to `abort` or use
 `SetUp`/`TearDown` instead.
 
+## Skipping test execution
+
+Related to pseudo assertions `SUCCEED()` and `FAIL()` you can prevent further test
+execution with the `GTEST_SKIP()` macro.
+
+`GTEST_SKIP` can be used in test cases or in `SetUp()` methods of classes inherited
+from either `::testing::Environment` or `::testing::Test`. The latter is a convenient
+way to check for preconditions of the system under test during runtime and skip
+the test in a meaningful way.
+
+Based on googletest's own test code:
+```c++
+class Fixture : public Test {
+ protected:
+  void SetUp() override {
+    GTEST_SKIP() << "skipping all tests for this fixture";
+  }
+};
+
+TEST_F(Fixture, SkipsOneTest) {
+  EXPECT_EQ(5, 7); // won't fail, it won't get executed
+}
+```
+
+The informational text is optional.
+
 ## Teaching googletest How to Print Your Values
 
 When a test assertion such as `EXPECT_EQ` fails, googletest prints the argument

From 1de97fd1c32e5eb4ff111b4e033a9e9aa848430f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Kr=C3=A4mer?= <sebkraemer@posteo.org>
Date: Thu, 15 Apr 2021 22:11:23 +0200
Subject: [PATCH 2/3] Apply suggestions from code review for GTEST_SKIP
 documentation

Extended example and some rewording by @ericschmidtatwork, thank you.

Co-authored-by: Eric Schmidt <shibumi@google.com>
---
 docs/advanced.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/advanced.md b/docs/advanced.md
index da7cf079..9b44a582 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -551,7 +551,7 @@ TEST_F(Fixture, SkipsOneTest) {
 }
 ```
 
-The informational text is optional.
+As with assertion macros, you can stream a custom message into `GTEST_SKIP()`.
 
 ## Teaching googletest How to Print Your Values
 

From 124e87a3038a34e0761fe5f96c06ace1f7b2442a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Kr=C3=A4mer?= <sebkraemer@posteo.org>
Date: Thu, 15 Apr 2021 22:26:14 +0200
Subject: [PATCH 3/3] Apply missing suggestions from code review for GTEST_SKIP

Co-authored-by: Eric Schmidt <shibumi@google.com>
---
 docs/advanced.md | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/docs/advanced.md b/docs/advanced.md
index 9b44a582..6c1d1a9a 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -529,25 +529,31 @@ partially-destructed state! You almost certainly want to `abort` or use
 
 ## Skipping test execution
 
-Related to pseudo assertions `SUCCEED()` and `FAIL()` you can prevent further test
-execution with the `GTEST_SKIP()` macro.
+Related to the assertions `SUCCEED()` and `FAIL()`, you can prevent further test
+execution at runtime with the `GTEST_SKIP()` macro. This is useful when you need
+to check for preconditions of the system under test during runtime and skip tests
+in a meaningful way.
 
-`GTEST_SKIP` can be used in test cases or in `SetUp()` methods of classes inherited
-from either `::testing::Environment` or `::testing::Test`. The latter is a convenient
-way to check for preconditions of the system under test during runtime and skip
-the test in a meaningful way.
+`GTEST_SKIP()` can be used in individual test cases or in the `SetUp()` methods of
+classes derived from either `::testing::Environment` or `::testing::Test`. For
+example:
 
-Based on googletest's own test code:
 ```c++
-class Fixture : public Test {
+TEST(SkipTest, DoesSkip) {
+  GTEST_SKIP() << "Skipping single test";
+  EXPECT_EQ(0, 1);  // Won't fail; it won't be executed
+}
+
+class SkipFixture : public ::testing::Test {
  protected:
   void SetUp() override {
-    GTEST_SKIP() << "skipping all tests for this fixture";
+    GTEST_SKIP() << "Skipping all tests for this fixture";
   }
 };
 
-TEST_F(Fixture, SkipsOneTest) {
-  EXPECT_EQ(5, 7); // won't fail, it won't get executed
+// Tests for SkipFixture won't be executed.
+TEST_F(SkipFixture, SkipsOneTest) {
+  EXPECT_EQ(5, 7);  // Won't fail
 }
 ```