From d91c50c1ae41793e2a2ecb84a0f66042a18e59dd Mon Sep 17 00:00:00 2001 From: Aleksandr Ivanov Date: Sat, 25 Jul 2015 23:53:59 +0300 Subject: [PATCH] updated Xdoc and Javadoc for ImportOrder and CustomImportOrder #1464 --- .../imports/CustomImportOrderCheck.java | 84 +++++++++++ .../checks/imports/ImportOrderCheck.java | 90 +++++++++--- src/xdocs/config_imports.xml | 131 +++++++++++++++--- 3 files changed, 272 insertions(+), 33 deletions(-) diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/CustomImportOrderCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/CustomImportOrderCheck.java index 5e1c60a90..312fb4598 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/CustomImportOrderCheck.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/CustomImportOrderCheck.java @@ -93,9 +93,93 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes; *

* * 
+ * Properties:
+ *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + *
nameDescriptiontypedefault value
customImportOrderRulesList of order declaration customizing by user.stringnull
standardPackageRegExpRegExp for STANDARD_JAVA_PACKAGE group imports.regular expression^(java|javax)\.
thirdPartyPackageRegExpRegExp for THIRDPARTY_PACKAGE group imports.regular expression.*
specialImportsRegExpRegExp for SPECIAL_IMPORTS group imports.regular expression^$
samePackageMatchingDepthNumber of first domains for SAME_PACKAGE group. + * Integer2
separateLineBetweenGroupsForce empty line separator between import groups. + * booleantrue
sortImportsInGroupAlphabeticallyForce grouping alphabetically, + * in ASCII sort order.booleanfalse
+ * + * 
  * For example:
  *
+ *

To configure the check so that it matches default Eclipse formatter configuration + * (tested on Kepler, Luna and Mars):

+ * + * 
+ *        
+ * <module name="CustomImportOrder">
+ *    <property name="customImportOrderRules"
+ *        value="STATIC###STANDARD_JAVA_PACKAGE###SPECIAL_IMPORTS"/>
+ *    <property name="specialImportsRegExp" value="org"/>
+ *    <property name="sortImportsInGroupAlphabetically" value="true"/>
+ *    <property name="separateLineBetweenGroups" value="true"/>
+ * </module>
+ *        
+ *
* + *

To configure the check so that it matches default IntelliJ IDEA formatter + * configuration (tested on v14):

+ * + * + *

+ * Note: "separated" option is disabled because IDEA default has blank line + * between "java" and static imports, and no blank line between + * "javax" and "java" + *

+ * + * 
+ *        
+ * <module name="CustomImportOrder">
+ *    <property name="customImportOrderRules"
+ *        value="THIRD_PARTY_PACKAGE###SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE
+ *        ###STATIC"/>
+ *    <property name="specialImportsRegExp" value="^javax\."/>
+ *    <property name="standardPackageRegExp" value="^java\."/>
+ *    <property name="sortImportsInGroupAlphabetically" value="true"/>
+ *    <property name="separateLineBetweenGroups" value="false"/>
+ *</module>
+ *        
+ *
+ * + *

To configure the check so that it matches default NetBeans formatter + * configuration (tested on v8):

+ * + * + * + *<module name="CustomImportOrder"/> + * + *

To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use + * thirdPartyPackageRegExp and standardPackageRegExp options.

* 
  * 
  * <module name="CustomImportOrder">
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/ImportOrderCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/ImportOrderCheck.java
index 68296e505..42663be92 100644
--- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/ImportOrderCheck.java
+++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/ImportOrderCheck.java
@@ -43,17 +43,87 @@ import com.puppycrawl.tools.checkstyle.checks.AbstractOptionCheck;
  * like non static imports (@see {@link ImportOrderOption}
  * 
  *
+ * 
+ * Properties:
+ * 

+ * 
+ *   
+ *   
+ *   
+ *       
+ *   
+ *       
+ *   
+ *   
+ *   
+ * 
nameDescriptiontypedefault value
optionpolicy on the relative order between regular imports and static
+ *       imports{@link ImportOrderOption}under
groupslist of imports groups (every group identified either by a common
+ *       prefix string, or by a regular expression enclosed in forward slashes (e.g. /regexp/)list of stringsempty list
orderedwhether imports within group should be sortedBooleantrue
separatedwhether imports groups should be separated by, at least,
+ *       one blank lineBooleanfalse
caseSensitivewhether string comparison should be case sensitive or not.
+ *       Case sensitive sorting is in ASCII sort orderBooleantrue
sortStaticImportsAlphabeticallywhether static imports grouped by top or
+ *       bottom option are sorted alphabetically or notBooleanfalse

+ *
  * 

  * Example:
  * 

+ * 
To configure the check so that it matches default Eclipse formatter configuration
+ *    (tested on Kepler, Luna and Mars):

+ * 
    
+ *     
  • group of static imports is on the top
    • 
+ *     
  • groups of non-static imports: "java" then "javax"
+ *         packages first, then "org" and then all other imports
    • 
+ *     
  • imports will be sorted in the groups
    • 
+ *     
  • groups are separated by, at least, one blank line
    • 
+ * 

  *
  * 
- *  <module name="ImportOrder">
- *    <property name="groups" value="java,javax"/>
+ * <module name="ImportOrder">
+ *    <property name="groups" value="/^javax?\./,org"/>
  *    <property name="ordered" value="true"/>
- *    <property name="caseSensitive" value="false"/>
+ *    <property name="separated" value="true"/>
  *    <property name="option" value="above"/>
- *  </module>
+ *    <property name="sortStaticImportsAlphabetically" value="true"/>
+ * </module>
+ * 

+ *
+ * 
To configure the check so that it matches default IntelliJ IDEA formatter configuration
+ *    (tested on v14):

+ * 
    
+ *     
  • group of static imports is on the bottom
    • 
+ *     
  • groups of non-static imports: all imports except of "javax" and
+ *         "java", then "javax" and "java"
    • 
+ *     
  • imports will be sorted in the groups
    • 
+ *     
  • groups are separated by, at least, one blank line
    • 
+ * 

+ *
+ *         

+ *         Note: "separated" option is disabled because IDEA default has blank line
+ *         between "java" and static imports, and no blank line between
+ *         "javax" and "java"
+ *         

+ *
+ * 
+ * <module name="ImportOrder">
+ *     <property name="groups" value="*,javax,java"/>
+ *     <property name="ordered" value="true"/>
+ *     <property name="separated" value="false"/>
+ *     <property name="option" value="bottom"/>
+ *     <property name="sortStaticImportsAlphabetically" value="true"/>
+ * </module>
+ * 

+ *
+ * 
To configure the check so that it matches default NetBeans formatter configuration
+ *    (tested on v8):

+ * 
    
+ *     
  • groups of non-static imports are not defined, all imports will be sorted
+ *         as a one group
    • 
+ *     
  • static imports are not separated, they will be sorted along with other imports
    • 
+ * 

+ *
+ * 
+ * <module name="ImportOrder">
+ *     <property name="option" value="inflow"/>
+ * </module>
  * 

  *
  * 

@@ -72,18 +142,6 @@ import com.puppycrawl.tools.checkstyle.checks.AbstractOptionCheck;
  * 

  *
  * 

- * Defaults:
- * 

- * 
    
- * 
  • import groups: none
    • 
- * 
  • separation: false
    • 
- * 
  • ordered: true
    • 
- * 
  • case sensitive: true
    • 
- * 
  • static import: under
    • 
- * 
  • sort static imports alphabetically: false
    • 
- * 

- *
- * 

  * Check also has on option making it more flexible:
  * sortStaticImportsAlphabetically - sets whether static imports grouped by
  * top or bottom option should be sorted alphabetically or
diff --git a/src/xdocs/config_imports.xml b/src/xdocs/config_imports.xml
index e9805c86f..f75e258c2 100644
--- a/src/xdocs/config_imports.xml
+++ b/src/xdocs/config_imports.xml
@@ -393,6 +393,10 @@ class FooBar {
           regular imports and static imports (see
           import orders)
          
+        

+        Examples section contains examples that
+          work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
+        

       
 
       
@@ -453,34 +457,71 @@ class FooBar {
         
       
 
-      
-        
To configure the check so that it requires that:

+      
+        
To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler, Luna and Mars):

         
    
-          
  • "java" and "javax" packages together first, then "org" and then all other imports
    • 
+          
  • group of static imports is on the top
    • 
+          
  • groups of non-static imports: "java" then "javax" packages first, then "org" and then all other imports
    • 
           
  • imports will be sorted in the groups
    • 
           
  • groups are separated by, at least, one blank line
    • 
-          
  • static imports are above each local groups
    • 
         

 
         
 <module name="ImportOrder">
-    <property name="groups" value="/^javax?\./,org"/>
-    <property name="ordered" value="true"/>
-    <property name="separated" value="true"/>
-    <property name="option" value="above"/>
+    <property name="groups" value="/^javax?\./,org"/>
+    <property name="ordered" value="true"/>
+    <property name="separated" value="true"/>
+    <property name="option" value="above"/>
+    <property name="sortStaticImportsAlphabetically" value="true"/>
 </module>
         
 
+        
To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):

+        
    
+          
  • group of static imports is on the bottom
    • 
+          
  • groups of non-static imports: all imports except of "javax" and "java", then "javax" and "java"
    • 
+          
  • imports will be sorted in the groups
    • 
+          
  • groups are separated by, at least, one blank line
    • 
+        

+
+        

+        Note: "separated" option is disabled because IDEA default has blank line
+        between "java" and static imports, and no blank line between
+        "javax" and "java"
+        

+
+        
+<module name="ImportOrder">
+    <property name="groups" value="*,javax,java"/>
+    <property name="ordered" value="true"/>
+    <property name="separated" value="false"/>
+    <property name="option" value="bottom"/>
+    <property name="sortStaticImportsAlphabetically" value="true"/>
+</module>
+        
+
+        
To configure the check so that it matches default NetBeans formatter configuration (tested on v8):

+        
    
+          
  • groups of non-static imports are not defined, all imports will be sorted as a one group
    • 
+          
  • static imports are not separated, they will be sorted along with other imports
    • 
+        

+
+        
+<module name="ImportOrder">
+    <property name="option" value="inflow"/>
+</module>
+        
+
         

           To configure the Check allows static imports grouped to the top
           being sorted alphabetically:
         

 
         
-<module name="ImportOrder">
-    <property name="sortStaticImportsAlphabetically" value="true"/>
-    <property name="option" value="top"/>
-</module>
+<module name="ImportOrder">
+    <property name="sortStaticImportsAlphabetically" value="true"/>
+    <property name="option" value="top"/>
+</module>
         
 
         
@@ -572,7 +613,7 @@ public class SomeClass { ... }
 
         
 <module name="ImportControl">
-    <property name="file" value="import-control.xml"/>
+    <property name="file" value="import-control.xml"/>
 </module>
         
 
@@ -584,9 +625,9 @@ public class SomeClass { ... }
 
         
 <import-control pkg="com.puppycrawl.tools.checkstyle">
-    <allow class="java\.awt\.I.*" regex="true"/>
+    <allow class="java\.awt\.I.*" regex="true"/>
     <allow class="java\.io\.(File|InputStream)" local-only="true"
-        regex="true"/>
+        regex="true"/>
 </import-control>
         
 
@@ -617,6 +658,10 @@ public class SomeClass { ... }
           by the user. If there is an import but its group is not specified in the
           configuration such an import should be placed at the end of the import list.
         

+        

+          Examples section contains examples that
+          work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
+        

       
 
       
@@ -720,7 +765,59 @@ public class SomeClass { ... }
         
       
 
-      
+      
+        
To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler, Luna and Mars):

+        
    
+          
  • group of static imports is on the top
    • 
+          
  • groups of non-static imports: "java" and "javax" packages first, then "org" and then all other imports
    • 
+          
  • imports will be sorted in the groups
    • 
+          
  • groups are separated by, at least, one blank line
    • 
+        

+        
+<module name="CustomImportOrder">
+    <property name="customImportOrderRules"
+        value="STATIC###STANDARD_JAVA_PACKAGE###SPECIAL_IMPORTS"/>
+    <property name="specialImportsRegExp" value="org"/>
+    <property name="sortImportsInGroupAlphabetically" value="true"/>
+    <property name="separateLineBetweenGroups" value="true"/>
+</module>
+        
+
+        
To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):

+        
    
+          
  • group of static imports is on the bottom
    • 
+          
  • groups of non-static imports: all imports except of "javax" and "java", then "javax" and "java"
    • 
+          
  • imports will be sorted in the groups
    • 
+          
  • groups are separated by, at least, one blank line
    • 
+        

+
+        

+        Note: "separated" option is disabled because IDEA default has blank line
+        between "java" and static imports, and no blank line between
+        "javax" and "java"
+        

+
+        
+<module name="CustomImportOrder">
+    <property name="customImportOrderRules"
+        value="THIRD_PARTY_PACKAGE###SPECIAL_IMPORTS###STANDARD_JAVA_PACKAGE###STATIC"/>
+    <property name="specialImportsRegExp" value="^javax\."/>
+    <property name="standardPackageRegExp" value="^java\."/>
+    <property name="sortImportsInGroupAlphabetically" value="true"/>
+    <property name="separateLineBetweenGroups" value="false"/>
+</module>
+        
+
+        
To configure the check so that it matches default NetBeans formatter configuration (tested on v8):

+        
    
+          
  • groups of non-static imports are not defined, all imports will be sorted as a one group
    • 
+          
  • static imports are not separated, they will be sorted along with other imports
    • 
+        

+
+        
+<module name="CustomImportOrder"/>
+        
+
         

           To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use
           thirdPartyPackageRegExp and standardPackageRegExp options.
@@ -728,7 +825,7 @@ public class SomeClass { ... }
         
 <module name="CustomImportOrder">
     <property name="customImportOrderRules"
-    value="STATIC###SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STANDARD_JAVA_PACKAGE"/>
+        value="STATIC###SAME_PACKAGE(3)###THIRD_PARTY_PACKAGE###STANDARD_JAVA_PACKAGE"/>
     <property name="thirdPartyPackageRegExp" value="com|org"/>
     <property name="standardPackageRegExp" value="^(java|javax)\."/>
 </module>