Polish documentation

README.md

@@ -76,8 +76,8 @@ For our own infrastructure, we rely on the following compile and test dependenci
 We welcome contributions of all shapes and forms! 🌞
 
 * If you have an idea for an extension, [open an issue](https://github.com/junit-pioneer/junit-pioneer/issues/new) and let's discuss.
-* If you want to help but don't know how, have a look at [the existing issues](https://github.com/junit-pioneer/junit-pioneer/issues), particularly [unassigned ones](https://github.com/junit-pioneer/junit-pioneer/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee) and those [marked as up for grabs](https://github.com/junit-pioneer/junit-pioneer/issues?q=is%3Aissue+is%3Aopen+label%3Aup-for-grabs).
-* If you want to have a chat about JUnit Pioneer, [join our discord](https://discord.gg/rHfJeCF) - we have a _#junit-pioneer_ channel. 😊
+* If you want to help but don't know how, have a look at [the existing issues](https://github.com/junit-pioneer/junit-pioneer/issues), particularly those marked [_up for grabs_](https://github.com/junit-pioneer/junit-pioneer/labels/%F0%9F%93%A2%20up%20for%20grabs) or [_good first issue_](https://github.com/junit-pioneer/junit-pioneer/labels/good%20first%20issue).
+* If you want to chat about JUnit Pioneer, [join our discord](https://discord.gg/rHfJeCF) - we have a _#junit-pioneer_ channel. 😊
 
 Before contributing, please read the [contribution guide](CONTRIBUTING.md) as well as [the code of conduct](CODE_OF_CONDUCT.md).
 
@@ -100,10 +100,9 @@ In lexicographic order, these are:
 		A Hungarian Java developer who spends more time on Twitch than recommended by his doctors and used creative and diligent contributions to fool everyone into believing he is a decent enough guy to get promoted to maintainer (in November 2020).
 		</dd>
 	<dt>Nicolai Parlog aka <a href="https://github.com/nipafx">nipafx</a></dt>
-	<dd>Java enthusiast with a passion for learning and sharing.
-		He does that in blog posts, articles, newsletters, and books; in <a href="https://twitter.com/nipafx">tweets</a>, repos, videos, and streams; at conferences and in-house trainings - more on all of that on <a href="https://nipafx.dev">nipafx.dev</a>.
-		That aside, he's best known for his head decor.
-		He co-founded the project in November 2016 and has maintained it ever since (although often very negligently).</dd>
+	<dd>Java enthusiast with a passion for learning and sharing, best known for his head decor.
+		He's a Java Developer Advocate at Oracle, organizer of <a href="https://accento.dev/">Accento</a>, occasional streamer, and more - check <a href="https://nipafx.dev">nipafx.dev</a> for the full list.
+		He co-founded JUnit Pioneer in November 2016 and has maintained it ever since (although often very negligently).</dd>
 	<dt>Simon Schrottner aka <a href="https://github.com/aepfli">aepfli</a></dt>
 	<dd>Bearded guy in Lederhosen, who loves to code, and loves to explore code quality, testing, and other tools that can improve the live of a software craftsman.
 		<a href="https://www.couchsurfing.com/people/simmens">Passionated couchsurfer</a> and <a href="https://www.facebook.com/togtrama">hobby event planner</a>.

docs/cartesian-product-v1.adoc

@@ -1,11 +1,14 @@
-:page-title: Old Cartesian product of all test parameters (deprecated in 1.6.0)
-:page-description: Extends JUnit Jupiter with `@CartesianProductTest`, a variant of parameterized tests that tests all combinations of its input
+:page-title: Cartesian Product of Parameters [removed in 2.0]
+:page-description: The JUnit 5 (Jupiter) extension `@CartesianTest` adds a variant of parameterized tests that executes a test for each possible combination of input arguments
 :page-unlist: true
 
-NOTE: The CartesianTest extension has undergone significant changes in 1.6.0.
+[NOTE]
+====
+The CartesianTest extension has undergone significant changes in 1.6.0.
 This included moving it into a new package.
-This here is the old variant, which is deprecated and will be removed in the 2.0 release (tentatively scheduled for 2022).
+This here is the old variant, which was deprecated in 1.6.0 and removed in 2.0.
 link:/docs/cartesian-product[For the new version, see here.]
+====
 
 From Wikipedia:
 
@@ -78,6 +81,7 @@ To demonstrate with a table:
 
 |===
 | # of test | value of `a`   | value of `b`   | value of `c`
+
 | 1st test  | "0"            | "0"            | "0"
 | 2nd test  | "0"            | "0"            | "1"
 | 3rd test  | "0"            | "1"            | "0"
@@ -118,6 +122,7 @@ To demonstrate with a table:
 
 |===
 | # of test | value of `number` | value of `character`
+
 | 1st test  | 1                 | "A"
 | 2nd test  | 1                 | "B"
 | 3rd test  | 2                 | "A"
@@ -237,6 +242,7 @@ To demonstrate with a table:
 
 |===
 | # of test | value of `myEnum` | value of `anotherEnum`
+
 | 1st test  | ONE               | BETA
 | 2nd test  | ONE               | GAMMA
 | 3rd test  | TWO               | BETA
@@ -263,7 +269,7 @@ void testEnumValues(int i, MyEnum myEnum) {
 
 === Range Source annotations
 
-Alternatively, you can annotate your test method with link:docs/range-sources[range source annotations].
+Alternatively, you can annotate your test method with link:/docs/range-sources[range source annotations].
 For _this purpose only_, range sources are repeatable.
 When you annotate your `@CartesianProductTest` with a range source, you specify the inputs to a single test parameter.
 This is _not_ like `@ParameterizedTest` where you have to define all inputs in a single `@ArgumentsSource`.
@@ -287,8 +293,10 @@ The second parameter can have any of the three values `0L`, `1L` or `2L`.
 `@CartesianProductTest` tests for all input combinations, that's `2 × 3`, so six tests in total.
 
 To demonstrate with a table:
+
 |===
 | # of test | value of `s` | value of `l`
+
 | 1st test  | 1            | 0L
 | 2nd test  | 1            | 1L
 | 3rd test  | 1            | 2L
@@ -297,7 +305,7 @@ To demonstrate with a table:
 | 6th test  | 2            | 2L
 |===
 
-For more information, please see the link:docs/range-sources[separate documentation about range sources].
+For more information, please see the link:/docs/range-sources[separate documentation about range sources].
 You can combine range sources with `@CartesianValueSource`, it works as you'd expect:
 
 [source,java]
@@ -347,6 +355,7 @@ To demonstrate with a table:
 
 |===
 | # of test  | value of `string` | value of `clazz` | value of `unit`
+
 | 1st test   | "Alpha"           | Runnable.class   | TimeUnit.DAYS
 | 2nd test   | "Alpha"           | Runnable.class   | TimeUnit.HOURS
 | 3rd test   | "Alpha"           | Cloneable.class  | TimeUnit.DAYS

docs/cartesian-product.adoc

@@ -1,5 +1,5 @@
-:page-title: Cartesian product of all test parameters
-:page-description: Extends JUnit Jupiter with `@CartesianTest`, a variant of parameterized tests that tests all combinations of its input
+:page-title: Cartesian Product of Parameters
+:page-description: The JUnit 5 (Jupiter) extension `@CartesianTest` adds a variant of parameterized tests that executes a test for each possible combination of input arguments
 :xp-demo-dir: ../src/demo/java
 :demo: {xp-demo-dir}/org/junitpioneer/jupiter/cartesian/CartesianTestExtensionDemo.java
 :people: {xp-demo-dir}/org/junitpioneer/jupiter/cartesian/PeopleProviderSources.java
@@ -23,9 +23,12 @@ Normally, this results in a lot of written test data parameters.
 For a more comfortable way you may use the `@CartesianTest` extension.
 The extension takes the test data parameter values and runs the test for every possible combination of them.
 
-NOTE: The CartesianTest extension has undergone significant changes in 1.6.0.
-This included moving it into a new package.
-link:/docs/cartesian-product-v1[The old variant] is deprecated and will be removed in the 2.0 release (tentatively scheduled for 2022).
+[NOTE]
+====
+The CartesianTest extension has undergone significant changes in 1.6.0.
+This here is the new variant, which, among other differences, lives in another package and does much of its work by annotating parameters directly.
+link:/docs/cartesian-product-v1[The old variant] was deprecated in 1.6.0 and removed in 2.0.
+====
 
 == Basic use
 
@@ -87,6 +90,7 @@ To demonstrate with a table:
 
 |===
 | # of test | value of `number` | value of `character`
+
 | 1st test  | 1                 | "A"
 | 2nd test  | 1                 | "B"
 | 3rd test  | 2                 | "A"
@@ -154,6 +158,7 @@ To demonstrate with a table:
 
 |===
 | # of test | value of `myEnum` | value of `anotherEnum`
+
 | 1st test  | ONE               | BETA
 | 2nd test  | ONE               | GAMMA
 | 3rd test  | TWO               | BETA
@@ -164,7 +169,7 @@ To demonstrate with a table:
 
 === Range source annotations
 
-You can annotate your test parameters with link:docs/range-sources[range source annotations].
+You can annotate your test parameters with link:/docs/range-sources[range source annotations].
 For _this purpose only_, range sources can be used on parameters.
 
 [source,java,indent=0]
@@ -178,8 +183,10 @@ The second parameter can have any of the three values `0L`, `1L` or `2L`.
 `@CartesianTest` tests for all input combinations, that's `2 × 3`, so six tests in total.
 
 To demonstrate with a table:
+
 |===
 | # of test | value of `s` | value of `l`
+
 | 1st test  | 1            | 0L
 | 2nd test  | 1            | 1L
 | 3rd test  | 1            | 2L
@@ -188,7 +195,7 @@ To demonstrate with a table:
 | 6th test  | 2            | 2L
 |===
 
-For more information, please see the link:docs/range-sources[separate documentation about range sources].
+For more information, please see the link:/docs/range-sources[separate documentation about range sources].
 
 == Defining arguments with factories
 
@@ -224,6 +231,7 @@ To demonstrate with a table:
 
 |===
 | # of test  | value of `string` | value of `clazz` | value of `unit`
+
 | 1st test   | "Alpha"           | Runnable.class   | TimeUnit.DAYS
 | 2nd test   | "Alpha"           | Runnable.class   | TimeUnit.HOURS
 | 3rd test   | "Alpha"           | Cloneable.class  | TimeUnit.DAYS

docs/default-locale-timezone.adoc

@@ -1,11 +1,11 @@
 :page-title: Default Locale and TimeZone
-:page-description: Extends JUnit Jupiter with `@DefaultLocale`, `@DefaultTimeZone`, which change the values returned from Locale.getDefault() and TimeZone.getDefault()
+:page-description: The JUnit 5 (Jupiter) extensions `@DefaultLocale` and `@DefaultTimeZone` change the runtime's default locale and time zone as returned from `Locale.getDefault()` and `TimeZone.getDefault()` for the duration of a test
 :xp-demo-dir: ../src/demo/java
 :demo: {xp-demo-dir}/org/junitpioneer/jupiter/DefaultLocaleTimezoneExtensionDemo.java
 
-The `@DefaultLocale` and `@DefaultTimeZone` annotations can be used to change the values returned from `Locale.getDefault()` and `TimeZone.getDefault()`.
+The `@DefaultLocale` and `@DefaultTimeZone` annotations can be used to change the values returned from `Locale.getDefault()` and `TimeZone.getDefault()`, respectively, which are often used implicitly when no specific locale or time zone is chosen.
 Both annotations work on the test class level and on the test method level, and are inherited from higher-level containers.
-After the annotated element has been executed the initial default value is restored.
+After the annotated element has been executed, the initial default value is restored.
 
 == `@DefaultLocale`
 

docs/disable-if-display-name.adoc

@@ -1,5 +1,5 @@
 :page-title: Disable Parameterized Test Based on DisplayName
-:page-description: Extends JUnit Jupiter with `@DisableIfDisplayName`, which selectively disables parameterized tests
+:page-description: The JUnit 5 (Jupiter) extension `@DisableIfDisplayName` selectively disables parameterized tests based on their display name
+:page-unlist: true
 
-This document has been moved and updated.
-See link:disable-parameterized-tests.adoc[the updated document].
+This document has been link:/docs/disable-parameterized-tests.adoc[moved and updated].

docs/disable-if-test-fails.adoc

@@ -1,9 +1,9 @@
 :page-title: Disable Tests if Others Fail
-:page-description: Disables all tests in a container once the first test failed
+:page-description:  The JUnit 5 (Jupiter) extension @DisableIfTestFails disables all tests in a class once the first test failed
 :xp-demo-dir: ../src/demo/java
 :demo: {xp-demo-dir}/org/junitpioneer/jupiter/DisableIfTestFailsExtensionDemo.java
 
-There are situations where when one test in a class fails, the remaining tests in the class don't need to be executed because their results offer little additional insight.
+There are situations where, when one test in a class fails, the remaining tests in the class don't need to be executed because their results offer little additional insight.
 In those situations, disabling the remaining tests can be preferable in order to avoid larger build logs and/or reduce the test suite's overall run time.
 By applying `@DisableIfTestFails` to the test class, all tests after the first failed one are disabled.
 
@@ -65,4 +65,4 @@ That means if...
 
 == Thread-Safety
 
-This extension is safe to use during https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[parallel test execution], but no guarantee can be given how soon after a failed test, other tests will be disabled, i.e. how soon other threads observe that "their" tests are supposed to be disabled.
+This extension is safe to use during https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[parallel test execution], but no guarantee can be given how soon after a failed test other tests will be disabled, i.e. how soon other threads observe that "their" tests are supposed to be disabled.

docs/disable-parameterized-tests.adoc

@@ -1,5 +1,5 @@
 :page-title: Disable Parameterized Test
-:page-description: Extends JUnit Jupiter with multiple extensions, which selectively disables parameterized tests
+:page-description: The JUnit 5 (Jupiter) extensions `@DisableIfDisplayName`, `@DisableIfArgument`, and more selectively disable parameterized tests based on their display name or argument values
 :xp-demo-dir: ../src/demo/java
 :demo: {xp-demo-dir}/org/junitpioneer/jupiter/params/DisableParameterizedExtensionDemo.java
 
@@ -35,8 +35,11 @@ If substrings are not powerful enough, you can also use regular expressions:
 include::{demo}[tag=disable_parameterized_regex]
 ----
 
-NOTE: Since JUnit Pioneer 1.5.0, using both `matches` and `contains` in a single annotation is no longer permitted.
+[NOTE]
+====
+Since JUnit Pioneer 1.5.0, using both `matches` and `contains` in a single annotation is no longer permitted.
 The reason is that it's not clear from reading the annotation whether it's *and* or *or* semantics, i.e. whether the display name needs to both match the regex *and* contain the substring to be disabled or whether fulfilling one criterion suffices.
+====
 
 == DisableIfArgument
 
@@ -172,9 +175,12 @@ These test invocations get disabled:
 
 Just like with `contains`, if any argument matches any expression from `matches`, the invocation gets disabled.
 
-NOTE: While the documentation uses `String` values for demonstration purposes, you can use it to disable tests with other parameter types.
+[NOTE]
+====
+While the documentation uses `String` values for demonstration purposes, you can use it to disable tests with other parameter types.
 However, the arguments will be converted to `String` with `Object#toString()` before evaluation.
 Make sure that your parameter types have a meaningful `toString` method.
+====
 
 == Thread-Safety
 

docs/disabled-until.adoc

@@ -1,5 +1,5 @@
-:page-title: Temporarily Disable a Test
-:page-description: Extends JUnit Jupiter with `@DisabledUntil` to temporarily disable a test.
+:page-title: Disable a Test Temporarily
+:page-description: The JUnit 5 (Jupiter) extension `@DisabledUntil` temporarily disables a test until a certain date
 :xp-demo-dir: ../src/demo/java
 :demo: {xp-demo-dir}/org/junitpioneer/jupiter/DisableUntilExtensionDemo.java
 
@@ -13,9 +13,12 @@ The only problem with this approach is remembering to activate the test again on
 The `@DisabledUntil` annotation may be used to disable a test only for a certain period of time.
 The test will be automatically executed again once the date supplied by the `date` parameter is reached.
 
-WARNING: Applying `@DisabledUntil` can make the test suite non-reproducible.
+[WARNING]
+====
+Applying `@DisabledUntil` can make the test suite non-reproducible.
 If a failing test is disabled during a build that then passes, rerunning that build after the "until" date would fail.
 A report entry is issued for every test that is disabled until a certain date.
+====
 
 == Usage
 

docs/docs-nav.yml

@@ -1,43 +1,41 @@
-# NOTE: The URLs need a trailing slash or the selected nav element
-#       won't be highlighted.
+# NOTES:
+#  * the URLs need a trailing slash or the selected nav element won't be highlighted
+#  * the entries are sorted lexicographically by their title (i.e. not their slug)
   - title: JUnit Pioneer Extensions
     children:
-      - title: "Cartesian product of all test parameters"
+      - title: "Cartesian Product of Parameters"
         url: /docs/cartesian-product/
       - title: "Clearing or Setting System Properties"
         url: /docs/system-properties/
       - title: "Clearing or Setting Environment Variables"
         url: /docs/environment-variables/
       - title: "Default Locale and TimeZone"
         url: /docs/default-locale-timezone/
-      - title: "Temporarily disable a test"
+      - title: "Disable a Test Temporarily"
         url: /docs/disabled-until/
       - title: "Disable If Test Fails"
         url: /docs/disable-if-test-fails/
       - title: "Disable Parameterized Tests"
         url: /docs/disable-parameterized-tests/
       - title: "Expected-to-Fail Tests"
         url: /docs/expected-to-fail-tests/
-      - title: "Issue information"
+      - title: "Injecting Resources"
+        url: /docs/resources/
+      - title: "Injecting Temporary Directories"
+        url: /docs/temp-directory/
+      - title: "Issue Information"
         url: /docs/issue/
       - title: "JSON Argument Source"
         url: /docs/json-argument-source
+      - title: "Measuring Test Run Time"
+        url: /docs/stopwatch/
       - title: "Publishing Report Entries"
         url: /docs/report-entries/
       - title: "Range Sources"
         url: /docs/range-sources/
-      - title: "Resources"
-        url: /docs/resources/
       - title: "Retrying Failing Tests"
         url: /docs/retrying-test/
       - title: "Standard Input and Output"
         url: /docs/standard-input-output/
-      - title: "Measuring time with a Stopwatch"
-        url: /docs/stopwatch/
-      - title: "Temporary Directories"
-        url: /docs/temp-directory/
-      - title: "Temporary Files and Directories (removed in 1.0)"
-        url: /docs/temp-directory-removed/
       - title: "Vintage @Test"
         url: /docs/vintage-test/
-