Polish documentation for 5.8 GA

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc

@@ -29,12 +29,12 @@ on GitHub.
 
 ==== Deprecations and Breaking Changes
 
-* Since the API Guardian dependency is no longer exported as a runtime but as a
+* Since the API Guardian dependency is no longer exported as a runtime but rather as a
   compile-only dependency to consuming Gradle projects, Gradle builds that define their own
   https://docs.gradle.org/current/userguide/declaring_dependencies.html#sec:what-are-dependency-configurations[dependency configurations]
   may be affected. For example, if the custom configuration is used to manipulate a source
   set's classpath directly, dependency attributes needed for Gradle's variant-aware
-  dependency management are dropped and API Guardian is missing from the compile
+  dependency management are dropped, and API Guardian is missing from the compile
   classpath. In that case, the Java compiler emits warnings which -- depending on your
   configured options -- may cause the build to fail. The solution is to avoid manipulating
   a source set's classpath directly. Instead, its dependency configurations should extend
@@ -71,8 +71,11 @@ on GitHub.
 ==== New Features and Improvements
 
 * New `junit-platform-suite-engine` module to execute declarative test suites on the JUnit
-  Platform.
-* Additional selectors in the suite API in the `junit-platform-suite-api` module.
+  Platform. See <<../user-guide/index.adoc#junit-platform-suite-engine, JUnit Platform
+  Suite Engine>> for details.
+* Additional selectors in the suite API in the `junit-platform-suite-api` module. See the
+  Javadoc of the `{suite-api-package}` package for a full list of supported annotations
+  and further details.
 * New `UniqueIdTrackingListener` which is a `TestExecutionListener` that tracks the unique
   IDs of all tests that were skipped or executed during the `TestPlan` and generates a
   file containing the unique IDs. The generated file can be used to rerun those tests --
@@ -90,12 +93,13 @@ on GitHub.
   nested container events when using the `EngineTestKit`. For example,
   `test(displayName("my test"))` can be used to match against a test whose display name is
   `my test`.
-* Generating Java Flight Recorder events via the `junit-platform-jfr` module is now also
-  supported on Java 8 Update 262 or higher, in addition to Java 11 or later. See
-  <<../user-guide/index.adoc#running-tests, Flight Recorder Support>> for details.
-* The `junit-platform-jfr` module now reports execution events for containers -- for
+* Generating Java Flight Recorder (JFR) events via the `junit-platform-jfr` module is now
+  also supported on Java 8 Update 262 or higher, in addition to Java 11 or later. See
+  <<../user-guide/index.adoc#running-tests-listeners-flight-recorder, Flight Recorder
+  Support>> for details.
+* The `junit-platform-jfr` module now publishes execution events for containers -- for
   example, test classes.
-* The `junit-platform-jfr` module now reports test discovery events for the launcher and
+* The `junit-platform-jfr` module now publishes test discovery events for the launcher and
   registered test engines.
 * New `ClassSource.from(URI)` static factory method for creating a `ClassSource` from a
   URI using the `class` scheme and optional query parameters specifying the line number
@@ -153,7 +157,9 @@ on GitHub.
 
 * Test classes can now be ordered _globally_ by supplying the fully-qualified name of a
   class implementing the `ClassOrderer` API as the value of the new
-  `junit.jupiter.testclass.order.default` configuration parameter.
+  `junit.jupiter.testclass.order.default` configuration parameter. See
+  <<../user-guide/index.adoc#writing-tests-test-execution-order-classes, Class Order>> for
+  details.
 * `@Nested` test classes can be ordered _locally_ via the new `@TestClassOrder` annotation
   in which a `ClassOrderer` can be specified.
 * `@ExtendWith` may now be used to register extensions declaratively via fields or

documentation/src/docs/asciidoc/user-guide/junit-platform-suite-engine.adoc

@@ -1,25 +1,29 @@
 [[junit-platform-suite-engine]]
 === JUnit Platform Suite Engine
 
-The JUnit Platform supports declarative definition and execution of suites of tests from
-_any_ test engine using the Junit Platform.
+The JUnit Platform supports the declarative definition and execution of suites of tests
+from _any_ test engine using the JUnit Platform.
 
+[[junit-platform-suite-engine-setup]]
 ==== Setup
 
-In addition to _at least one_ other test engine, you need the following artifacts and
-their dependencies on the classpath. See <<dependency-metadata>> for details regarding
-group IDs, artifact IDs, and versions.
+In addition to the `junit-platform-suite-api` and `junit-platform-suite-engine` artifacts,
+you need _at least one_ other test engine and its dependencies on the classpath. See
+<<dependency-metadata>> for details regarding group IDs, artifact IDs, and versions.
 
-===== Explicit Dependencies
+[[junit-platform-suite-engine-setup-required-dependencies]]
+===== Required Dependencies
 
-* `junit-platform-suite-api` in _test_ scope
+* `junit-platform-suite-api` in _test_ scope: artifact containing annotations needed to
+  configure a test suite
 * `junit-platform-suite-engine` in _test runtime_ scope: implementation of the
-                                `TestEngine` API for the declarative Junit Platform
-                                Suites
+  `TestEngine` API for declarative test suites
 
-NOTE: Both dependencies are aggregated in `junit-platform-suite` which can be used in
-_test_ scope.
+NOTE: Both of the required dependencies are aggregated in the `junit-platform-suite`
+artifact which can be declard in _test_ scope instead of declaring explicit dependencies
+on `junit-platform-suite-api` and `junit-platform-suite-engine`.
 
+[[junit-platform-suite-engine-setup-transitive-dependencies]]
 ===== Transitive Dependencies
 
 * `junit-platform-suite-commons` in _test_ scope
@@ -28,7 +32,8 @@ _test_ scope.
 * `junit-platform-commons` in _test_ scope
 * `opentest4j` in _test_ scope
 
-==== Test Suite
+[[junit-platform-suite-engine-example]]
+==== @Suite Example
 
 By annotating a class with `@Suite` it is marked as a test suite on the JUnit Platform.
 As seen in the following example, selector and filter annotations can then be used to
@@ -40,6 +45,6 @@ include::{testDir}/example/SuiteDemo.java[tags=user_guide]
 ----
 
 .Additional Configuration Options
-NOTE: There are more configuration options for discovering and filtering tests than just
-`@SelectPackages`. Please consult the Javadoc of the `{suite-api-package}` package for
-further details.
+NOTE: There are numerous configuration options for discovering and filtering tests in a
+test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
+list of supported annotations and further details.

documentation/src/docs/asciidoc/user-guide/running-tests.adoc

@@ -640,6 +640,7 @@ to reporting (see <<running-tests-junit-platform-runner-technical-names>>).
 You need the following artifacts and their dependencies on the classpath. See
 <<dependency-metadata>> for details regarding group IDs, artifact IDs, and versions.
 
+[[running-tests-junit-platform-runner-setup-explicit-dependencies]]
 ===== Explicit Dependencies
 
 * `junit-platform-runner` in _test_ scope: location of the `JUnitPlatform` runner
@@ -649,6 +650,7 @@ You need the following artifacts and their dependencies on the classpath. See
 * `junit-jupiter-engine` in _test runtime_ scope: implementation of the `TestEngine` API
   for JUnit Jupiter
 
+[[running-tests-junit-platform-runner-setup-transitive-dependencies]]
 ===== Transitive Dependencies
 
 * `junit-platform-suite-api` in _test_ scope

documentation/src/test/java/example/SuiteDemo.java

@@ -11,16 +11,18 @@
 package example;
 
 //tag::user_guide[]
+import org.junit.platform.suite.api.IncludeClassNamePatterns;
 import org.junit.platform.suite.api.SelectPackages;
 import org.junit.platform.suite.api.Suite;
 import org.junit.platform.suite.api.SuiteDisplayName;
 
 @Suite
 @SuiteDisplayName("JUnit Platform Suite Demo")
 @SelectPackages("example")
+@IncludeClassNamePatterns(".*Tests")
 //end::user_guide[]
 @org.junit.platform.suite.api.ExcludeTags("exclude")
 //tag::user_guide[]
-public class SuiteDemo {
+class SuiteDemo {
 }
 //end::user_guide[]