Polish Javadoc and User Guide regarding @⁠Suite support

(cherry picked from commit 569dbc7)

Author: sbrannen

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

@@ -1,8 +1,8 @@
 [[junit-platform-suite-engine]]
 === JUnit Platform Suite Engine
 
-The Suite Engine supports the declarative selection and execution of tests from
-_any_ test engine on the JUnit Platform using the <<launcher-api>>.
+The Suite Engine supports the declarative selection and execution of tests from _any_ test
+engine on the JUnit Platform using the <<launcher-api>>.
 
 image::junit-platform-suite-engine-diagram.svg[role=text-center]
 
@@ -36,9 +36,9 @@ on `junit-platform-suite-api` and `junit-platform-suite-engine`.
 [[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
-control the contents of the suite.
+Annotate a class with `@Suite` to have it marked as a test suite on the JUnit Platform. As
+seen in the following example, selector and filter annotations can be used to control the
+contents of the suite.
 
 [source,java,indent=0]
 ----
@@ -53,26 +53,28 @@ list of supported annotations and further details.
 ==== @BeforeSuite and @AfterSuite
 
 `@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a
-`@Suite`-annotated class. They will be executed respectively before and after
-all tests of the test suite.
+`@Suite`-annotated class. They will be executed before and after all tests of the test
+suite, respectively.
 
 [source,java,indent=0]
 ----
 include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]
 ----
 
 [[junit-platform-suite-engine-duplicate-test-execution]]
-==== Duplicate test execution
+==== Duplicate Test Execution
 
-Depending on the declared test selection, different suites may contain the same tests,
-potentially with different configurations.
-Moreover, tests in a suite are executed in addition to the tests executed by every other
-test engine. This can result in the same tests being executed twice.
+Depending on the declared selectors, different suites may contain the same tests,
+potentially with different configurations. Moreover, tests in a suite are executed in
+addition to the tests executed by every other test engine, which can result in the same
+tests being executed twice.
 
 image::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[role=text-center]
 
-This can be prevented by configuring your build tool to only include the
-`junit-platform-suite` engine. Or by using a naming pattern. For example, name all suites
-`*Suite` and all tests `*Test` and configure your build tool to only include the former.
+To prevent duplicate execution of tests within a suite, configure your build tool to
+include only the `junit-platform-suite` engine, or use a custom naming pattern. For
+example, name all suites `*Suite` and all tests `*Test`, and configure your build tool to
+include only the former.
 
-Alternatively, consider <<running-tests-tags, using tags>> to select specific groups of tests.
+Alternatively, consider <<running-tests-tags, using tags>> to select specific groups of
+tests.

documentation/src/docs/asciidoc/user-guide/advanced-topics/testkit.adoc

@@ -4,9 +4,8 @@
 === JUnit Platform Test Kit
 
 The `junit-platform-testkit` artifact provides support for executing a test plan on the
-JUnit Platform and then verifying the expected results. As of JUnit Platform
-{version}, this support is limited to the execution of a single `TestEngine` (see
-<<testkit-engine>>).
+JUnit Platform and then verifying the expected results. This support is currently limited
+to the execution of a single `TestEngine` (see <<testkit-engine>>).
 
 [[testkit-engine]]
 ==== Engine Test Kit

documentation/src/plantuml/junit-platform-suite-engine-duplicate-test-execution-diagram.puml

@@ -26,5 +26,5 @@ together {
 "Jupiter Test Engine (@Suite)"  --> "Example Test A (@Suite)" : discovers and executes
 
 "JUnit Platform" --> "Jupiter Test Engine": forwards request
-"Jupiter Test Engine" --> "Example Test A" #line:red;line.bold;text:red : also discover and executes!
+"Jupiter Test Engine" --> "Example Test A" #line:red;line.bold;text:red : also discovers and executes!
 @enduml

junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java

@@ -41,19 +41,17 @@
  * and the configuration parameters from the discovery request that discovered
  * the suite. Annotating a suite with
  * {@link DisableParentConfigurationParameters @DisableParentConfigurationParameters}
- * annotation disables the latter as a source of parameters so that only explicit
- * configuration parameters are taken into account.
+ * disables the latter as a source of parameters so that only explicit configuration
+ * parameters are taken into account.
  *
- * <p>Note: Depending on the declared test selection, different suites may contain the
- * same tests, potentially with different configurations.
- * Moreover, tests in a suite are executed in addition to the tests executed by every
- * other test engine. This can result in the same tests being executed twice and can be
- * prevented by configuring your build tool to only include the
- * {@code junit-platform-suite} engine. Or by using a naming pattern. For example, name
- * all suites {@code *Suite} and all tests {@code *Test} and configure your build tool
- * to only include the former.
- *
- * <p>Alternatively, consider using tags to select specific groups of tests.
+ * <p>Note: Depending on the declared selectors, different suites may contain the
+ * same tests, potentially with different configurations. Moreover, tests in a suite
+ * are executed in addition to the tests executed by every other test engine, which
+ * can result in the same tests being executed twice. To prevent that, configure
+ * your build tool to include only the {@code junit-platform-suite} engine, or use
+ * a custom naming pattern. For example, name all suites {@code *Suite} and all
+ * tests {@code *Test}, and configure your build tool to include only the former.
+ * Alternatively, consider using tags to select specific groups of tests.
  *
  * @since 1.8
  * @see Select