Apply suggestions from the code review

Author: vdmitrienko

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.0-M1.adoc

@@ -90,7 +90,7 @@ JUnit repository on GitHub.
 * Allow determining "shared resources" at runtime via the new `@ResourceLock#providers`
   attribute that accepts implementations of `ResourceLocksProvider`.
 * Allow declaring "shared resources" for _direct_ child nodes via the new
-  `@ResourceLock(target = CHILDREN)` attribute. It may improve parallelization when
+  `@ResourceLock(target = CHILDREN)` attribute. This may improve parallelization when
   a test class declares a `READ` lock, but only a few methods hold a `READ_WRITE` lock.
 * Extensions that implement `TestInstancePreConstructCallback`, `TestInstanceFactory`,
   `TestInstancePostProcessor`, `ParameterResolver`, or `InvocationInterceptor` may

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

@@ -3035,15 +3035,15 @@ the `{ResourceLockTarget}` enum.
 
 Using the `target = CHILDREN` in a class-level `{ResourceLock}` annotation
 has the same semantics as adding an annotation with the same `value` and `mode`
-to each test method declared in this class.
+to each test method and nested test class declared in this class.
 
-It may improve parallelization when a test class declares a `READ` lock,
+This may improve parallelization when a test class declares a `READ` lock,
 but only a few methods hold a `READ_WRITE` lock.
 
 Tests in the following example would run in the `SAME_THREAD` if the `{ResourceLock}`
-doesn't have the `target = CHILDREN`. This is because the test class declares a `READ`
+didn't have `target = CHILDREN`. This is because the test class declares a `READ`
 shared resource, but one test method holds a `READ_WRITE` lock,
-which forces the `SAME_THREAD` execution mode for all the test methods.
+which would force the `SAME_THREAD` execution mode for all the test methods.
 
 [source,java]
 .Declaring shared resources for child nodes with `target` attribute

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/ResourceLock.java

@@ -67,10 +67,10 @@
  *
  * <p>Using the {@link ResourceLockTarget#CHILDREN} in a class-level
  * annotation has the same semantics as adding an annotation with the same
- * {@link #value()} and {@link #mode()} to each test method declared
- * in this class.
+ * {@link #value()} and {@link #mode()} to each test method and nested test
+ * class declared in this class.
  *
- * <p>It may improve parallelization when a test class declares a
+ * <p>This may improve parallelization when a test class declares a
  * {@link ResourceAccessMode#READ READ} lock, but only a few methods hold
  * {@link ResourceAccessMode#READ_WRITE READ_WRITE} lock.
  *

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/ResourceLockTarget.java

@@ -37,8 +37,11 @@ public enum ResourceLockTarget {
 	 *     <li>a test class
 	 *     - test methods and nested test classes declared in the class.</li>
 	 *     <li>a nested test class
-	 *     - test methods declared in the nested class.</li>
-	 *     <li>a test method - considered to have no children.</li>
+	 *     - test methods and nested test classes declared in the nested class.
+	 *     </li>
+	 *     <li>a test method
+	 *     - considered to have no children. Using {@code CHILDREN} for
+	 *     a test method results in an exception.</li>
 	 * </ul>
 	 */
 	CHILDREN