Reword the SKIP docs a bit

1 files changed, 26 insertions, 11 deletions

diff --git a/docs/skipping-passing-failing.md b/docs/skipping-passing-failing.md
index 8ae52541..72c9f775 100644
--- a/docs/skipping-passing-failing.md
+++ b/docs/skipping-passing-failing.md
@@ -5,11 +5,18 @@
 
 > [Introduced](https://github.com/catchorg/Catch2/pull/2360) in Catch2 X.Y.Z.
 
-In some situations it may not be possible to meaningfully execute a test case, for example when the system under test is missing certain hardware capabilities.
-If the required conditions can only be determined at runtime, it often doesn't make sense to consider such a test case as either passed or failed, because it simply can not run at all.
-To properly express such scenarios, Catch2 allows to explicitly _skip_ test cases, using the `SKIP` macro:
+In some situations it may not be possible to meaningfully execute a test case,
+for example when the system under test is missing certain hardware capabilities.
+If the required conditions can only be determined at runtime, it often
+doesn't make sense to consider such a test case as either passed or failed,
+because it simply can not run at all.
 
-**SKIP(** [streamable expression] **)**
+To properly express such scenarios, Catch2 provides a way to explicitly
+_skip_ test cases, using the `SKIP` macro:
+
+```
+SKIP( [streamable expression] )
+```
 
 Example usage:
 
@@ -24,7 +31,8 @@ TEST_CASE("copy files between drives") {
 
 This test case is then reported as _skipped_ instead of _passed_ or _failed_.
 
-The `SKIP` macro behaves similarly to an explicit [`FAIL`](logging.md#top), in that it is the last expression that will be executed:
+The `SKIP` macro behaves similarly to an explicit [`FAIL`](#passing-and-failing-test-cases),
+in that it is the last expression that will be executed:
 
 ```c++
 TEST_CASE("my test") {
@@ -34,7 +42,8 @@ TEST_CASE("my test") {
 }
 ```
 
-However a failed assertion _before_ a `SKIP` still causes the entire test case to fail:
+However a failed assertion _before_ a `SKIP` still causes the entire
+test case to fail:
 
 ```c++
 TEST_CASE("failing test") {
@@ -45,7 +54,8 @@ TEST_CASE("failing test") {
 
 ### Interaction with Sections and Generators
 
-Sections, nested sections as well as test cases with [generators](generators.md#top) can all be individually skipped, with the rest executing as usual:
+Sections, nested sections as well as specific outputs from [generators](generators.md#top)
+can all be individually skipped, with the rest executing as usual:
 
 ```c++
 TEST_CASE("complex test case") {
@@ -62,12 +72,17 @@ TEST_CASE("complex test case") {
 }
 ```
 
-This test case will report 5 passing assertions; one for each of the three values in section `a1`, as well as one for each in `a2`, except for when `value == 4`.
+This test case will report 5 passing assertions; one for each of the three
+values in section `a1`, and then two in section `a2`, from values 2 and 4.
 
-Note that as soon as one section is skipped, the entire test case will be reported as _skipped_ (unless there is a failing assertion, in which case it will be reported as _failed_ instead).
+Note that as soon as one section is skipped, the entire test case will
+be reported as _skipped_ (unless there is a failing assertion, in which
+case the test is handled as _failed_ instead).
 
-If all test cases in a run are skipped, Catch2 returns a non-zero exit code by default.
-This can be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override) flag.
+Note that if all test cases in a run are skipped, Catch2 returns a non-zero
+exit code, same as it does if no test cases have run. This behaviour can
+be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override)
+flag.
 
 
 ## Passing and failing test cases