8186736: Spec clarifications for IllegalArgumentException throwing - ModuleLayer.defineX methods

[Alan Bateman]

The description for the IllegalArgumentException thrown by the 
ModuleLayer.defineModulesXXX methods isn't very clear. Attached is the 
proposed patch to improve the wording, there are no implementation 
changes. Mandy has already reviewed the CSR 
(https://bugs.openjdk.java.net/browse/JDK-8192980) so it doesn't 
strictly need additional reviewers, unless anyone is interested.

-Alan


diff -r 0b42613e35bf src/java.base/share/classes/java/lang/ModuleLayer.java
--- a/src/java.base/share/classes/java/lang/ModuleLayer.java    Mon Dec 
04 13:24:00 2017 +0530
+++ b/src/java.base/share/classes/java/lang/ModuleLayer.java    Tue Dec 
05 11:55:38 2017 +0000
@@ -322,8 +322,8 @@
       * @return The newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent of the given configuration is not the 
configuration
-     *         for this layer
+     *         If the given configuration has more than one parent or 
the parent
+     *         of the configuration is not the configuration for this layer
       * @throws LayerInstantiationException
       *         If the layer cannot be created for any of the reasons 
specified
       *         by the static {@code defineModulesWithOneLoader} method
@@ -364,8 +364,8 @@
       * @return The newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent of the given configuration is not the 
configuration
-     *         for this layer
+     *         If the given configuration has more than one parent or 
the parent
+     *         of the configuration is not the configuration for this layer
       * @throws LayerInstantiationException
       *         If the layer cannot be created for any of the reasons 
specified
       *         by the static {@code defineModulesWithManyLoaders} method
@@ -403,8 +403,8 @@
       * @return The newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent of the given configuration is not the 
configuration
-     *         for this layer
+     *         If the given configuration has more than one parent or 
the parent
+     *         of the configuration is not the configuration for this layer
       * @throws LayerInstantiationException
       *         If the layer cannot be created for any of the reasons 
specified
       *         by the static {@code defineModules} method
@@ -473,8 +473,8 @@
       * @return A controller that controls the newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent configurations do not match the 
configuration of
-     *         the parent layers, including order
+     *         If the parent(s) of the given configuration do not match the
+     *         configuration of the parent layers, including order
       * @throws LayerInstantiationException
       *         If all modules cannot be defined to the same class 
loader for any
       *         of the reasons listed above
@@ -546,8 +546,8 @@
       * @return A controller that controls the newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent configurations do not match the 
configuration of
-     *         the parent layers, including order
+     *         If the parent(s) of the given configuration do not match the
+     *         configuration of the parent layers, including order
       * @throws LayerInstantiationException
       *         If the layer cannot be created because the 
configuration contains
       *         a module named "{@code java.base}" or a module contains 
a package
@@ -637,8 +637,8 @@
       * @return A controller that controls the newly created layer
       *
       * @throws IllegalArgumentException
-     *         If the parent configurations do not match the 
configuration of
-     *         the parent layers, including order
+     *         If the parent(s) of the given configuration do not match the
+     *         configuration of the parent layers, including order
       * @throws LayerInstantiationException
       *         If creating the layer fails for any of the reasons 
listed above
       * @throws SecurityException