Issue checkstyle#15626: Explain what happens when an import matches t…

…wo or more groups

src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/ImportOrderCheck.java

@@ -73,7 +73,9 @@
  * <li>
  * Property {@code groups} - Specify list of <b>type import</b> groups. Every group identified
  * either by a common prefix string, or by a regular expression enclosed in forward slashes
- * (e.g. {@code /regexp/}). All type imports, which does not match any group, falls into an
+ * (e.g. {@code /regexp/}). If an import matches two or more groups,
+ * the best match is selected (closest to the start, and the longest match).
+ * All type imports, which does not match any group, falls into an
  * additional group, located at the end.
  * Thus, the empty list of type groups (the default value) means one group for all type imports.
  * Type is {@code java.lang.String[]}.
@@ -116,7 +118,9 @@
  * <li>
  * Property {@code staticGroups} - Specify list of <b>static</b> import groups. Every group
  * identified either by a common prefix string, or by a regular expression enclosed in forward
- * slashes (e.g. {@code /regexp/}). All static imports, which does not match any group, fall into
+ * slashes (e.g. {@code /regexp/}). If an import matches two or more groups,
+ * the best match is selected (closest to the start, and the longest match).
+ * All static imports, which does not match any group, fall into
  * an additional group, located at the end. Thus, the empty list of static groups (the default
  * value) means one group for all static imports. This property has effect only when the property
  * {@code option} is set to {@code top} or {@code bottom}.
@@ -184,6 +188,8 @@ public class ImportOrderCheck
     /**
      * Specify list of <b>type import</b> groups. Every group identified either by a common prefix
      * string, or by a regular expression enclosed in forward slashes (e.g. {@code /regexp/}).
+     * If an import matches two or more groups,
+     * the best match is selected (closest to the start, and the longest match).
      * All type imports, which does not match any group, falls into an additional group,
      * located at the end. Thus, the empty list of type groups (the default value) means one group
      * for all type imports.
@@ -193,6 +199,8 @@ public class ImportOrderCheck
     /**
      * Specify list of <b>static</b> import groups. Every group identified either by a common prefix
      * string, or by a regular expression enclosed in forward slashes (e.g. {@code /regexp/}).
+     * If an import matches two or more groups,
+     * the best match is selected (closest to the start, and the longest match).
      * All static imports, which does not match any group, fall into an additional group, located
      * at the end. Thus, the empty list of static groups (the default value) means one group for all
      * static imports. This property has effect only when the property {@code option} is set to
@@ -288,7 +296,9 @@ public void setOption(String optionStr) {
     /**
      * Setter to specify list of <b>type import</b> groups. Every group identified either by a
      * common prefix string, or by a regular expression enclosed in forward slashes
-     * (e.g. {@code /regexp/}). All type imports, which does not match any group, falls into an
+     * (e.g. {@code /regexp/}). If an import matches two or more groups,
+     * the best match is selected (closest to the start, and the longest match).
+     * All type imports, which does not match any group, falls into an
      * additional group, located at the end. Thus, the empty list of type groups (the default value)
      * means one group for all type imports.
      *
@@ -303,7 +313,9 @@ public void setGroups(String... packageGroups) {
     /**
      * Setter to specify list of <b>static</b> import groups. Every group identified either by a
      * common prefix string, or by a regular expression enclosed in forward slashes
-     * (e.g. {@code /regexp/}). All static imports, which does not match any group, fall into an
+     * (e.g. {@code /regexp/}). If an import matches two or more groups,
+     * the best match is selected (closest to the start, and the longest match).
+     * All static imports, which does not match any group, fall into an
      * additional group, located at the end. Thus, the empty list of static groups (the default
      * value) means one group for all static imports. This property has effect only when
      * the property {@code option} is set to {@code top} or {@code bottom}.

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/imports/ImportOrderCheck.xml

@@ -43,7 +43,9 @@
             <property default-value="" name="groups" type="java.lang.String[]">
                <description>Specify list of &lt;b&gt;type import&lt;/b&gt; groups. Every group identified
  either by a common prefix string, or by a regular expression enclosed in forward slashes
- (e.g. {@code /regexp/}). All type imports, which does not match any group, falls into an
+ (e.g. {@code /regexp/}). If an import matches two or more groups,
+ the best match is selected (closest to the start, and the longest match).
+ All type imports, which does not match any group, falls into an
  additional group, located at the end.
  Thus, the empty list of type groups (the default value) means one group for all type imports.</description>
             </property>
@@ -78,7 +80,9 @@
             <property default-value="" name="staticGroups" type="java.lang.String[]">
                <description>Specify list of &lt;b&gt;static&lt;/b&gt; import groups. Every group
  identified either by a common prefix string, or by a regular expression enclosed in forward
- slashes (e.g. {@code /regexp/}). All static imports, which does not match any group, fall into
+ slashes (e.g. {@code /regexp/}). If an import matches two or more groups,
+ the best match is selected (closest to the start, and the longest match).
+ All static imports, which does not match any group, fall into
  an additional group, located at the end. Thus, the empty list of static groups (the default
  value) means one group for all static imports. This property has effect only when the property
  {@code option} is set to {@code top} or {@code bottom}.</description>

src/xdocs/checks/imports/importorder.xml

@@ -52,7 +52,7 @@
             </tr>
             <tr>
               <td>groups</td>
-              <td>Specify list of <b>type import</b> groups. Every group identified either by a common prefix string, or by a regular expression enclosed in forward slashes (e.g. <code>/regexp/</code>). All type imports, which does not match any group, falls into an additional group, located at the end. Thus, the empty list of type groups (the default value) means one group for all type imports.</td>
+              <td>Specify list of <b>type import</b> groups. Every group identified either by a common prefix string, or by a regular expression enclosed in forward slashes (e.g. <code>/regexp/</code>). If an import matches two or more groups, the best match is selected (closest to the start, and the longest match). All type imports, which does not match any group, falls into an additional group, located at the end. Thus, the empty list of type groups (the default value) means one group for all type imports.</td>
               <td><a href="../../property_types.html#String.5B.5D">String[]</a></td>
               <td><code>{}</code></td>
               <td>3.2</td>
@@ -94,7 +94,7 @@
             </tr>
             <tr>
               <td>staticGroups</td>
-              <td>Specify list of <b>static</b> import groups. Every group identified either by a common prefix string, or by a regular expression enclosed in forward slashes (e.g. <code>/regexp/</code>). All static imports, which does not match any group, fall into an additional group, located at the end. Thus, the empty list of static groups (the default value) means one group for all static imports. This property has effect only when the property <code>option</code> is set to <code>top</code> or <code>bottom</code>.</td>
+              <td>Specify list of <b>static</b> import groups. Every group identified either by a common prefix string, or by a regular expression enclosed in forward slashes (e.g. <code>/regexp/</code>). If an import matches two or more groups, the best match is selected (closest to the start, and the longest match). All static imports, which does not match any group, fall into an additional group, located at the end. Thus, the empty list of static groups (the default value) means one group for all static imports. This property has effect only when the property <code>option</code> is set to <code>top</code> or <code>bottom</code>.</td>
               <td><a href="../../property_types.html#String.5B.5D">String[]</a></td>
               <td><code>{}</code></td>
               <td>8.12</td>