updated Xdoc and Javadoc for ImportOrder and CustomImportOrder #1464
This commit is contained in:
Aleksandr Ivanov
Roman Ivanov
parent
c3f9d975a8
commit
d91c50c1ae
|
|
@ -93,9 +93,93 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes;
|
|||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* Properties:
|
||||
* </pre>
|
||||
* <table summary="Properties" border="1">
|
||||
* <tr><th>name</th><th>Description</th><th>type</th><th>default value</th></tr>
|
||||
* <tr><td>customImportOrderRules</td><td>List of order declaration customizing by user.</td>
|
||||
* <td>string</td><td>null</td></tr>
|
||||
* <tr><td>standardPackageRegExp</td><td>RegExp for STANDARD_JAVA_PACKAGE group imports.</td>
|
||||
* <td>regular expression</td><td>^(java|javax)\.</td></tr>
|
||||
* <tr><td>thirdPartyPackageRegExp</td><td>RegExp for THIRDPARTY_PACKAGE group imports.</td>
|
||||
* <td>regular expression</td><td>.*</td></tr>
|
||||
* <tr><td>specialImportsRegExp</td><td>RegExp for SPECIAL_IMPORTS group imports.</td>
|
||||
* <td>regular expression</td><td>^$</td></tr>
|
||||
* <tr><td>samePackageMatchingDepth</td><td>Number of first domains for SAME_PACKAGE group.
|
||||
* </td><td>Integer</td><td>2</td></tr>
|
||||
* <tr><td>separateLineBetweenGroups</td><td>Force empty line separator between import groups.
|
||||
* </td><td>boolean</td><td>true</td></tr>
|
||||
* <tr><td>sortImportsInGroupAlphabetically</td><td>Force grouping alphabetically,
|
||||
* in ASCII sort order.</td><td>boolean</td><td>false</td></tr>
|
||||
* </table>
|
||||
*
|
||||
* <pre>
|
||||
* For example:
|
||||
* </pre>
|
||||
* <p>To configure the check so that it matches default Eclipse formatter configuration
|
||||
* (tested on Kepler, Luna and Mars):</p>
|
||||
* <ul>
|
||||
* <li>group of static imports is on the top</li>
|
||||
* <li>groups of non-static imports: "java" and "javax" packages
|
||||
* first, then "org" and then all other imports</li>
|
||||
* <li>imports will be sorted in the groups</li>
|
||||
* <li>groups are separated by, at least, one blank line</li>
|
||||
* </ul>
|
||||
* <pre>
|
||||
* <code>
|
||||
* <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>
|
||||
* </code>
|
||||
* </pre>
|
||||
*
|
||||
* <p>To configure the check so that it matches default IntelliJ IDEA formatter
|
||||
* configuration (tested on v14):</p>
|
||||
* <ul>
|
||||
* <li>group of static imports is on the bottom</li>
|
||||
* <li>groups of non-static imports: all imports except of "javax"
|
||||
* and "java", then "javax" and "java"</li>
|
||||
* <li>imports will be sorted in the groups</li>
|
||||
* <li>groups are separated by, at least, one blank line</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* Note: "separated" option is disabled because IDEA default has blank line
|
||||
* between "java" and static imports, and no blank line between
|
||||
* "javax" and "java"
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <code>
|
||||
* <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>
|
||||
* </code>
|
||||
* </pre>
|
||||
*
|
||||
* <p>To configure the check so that it matches default NetBeans formatter
|
||||
* configuration (tested on v8):</p>
|
||||
* <ul>
|
||||
* <li>groups of non-static imports are not defined, all imports will be sorted as a one
|
||||
* group</li>
|
||||
* <li>static imports are not separated, they will be sorted along with other imports</li>
|
||||
* </ul>
|
||||
*
|
||||
* <code>
|
||||
*<module name="CustomImportOrder"/>
|
||||
* </code>
|
||||
* <p>To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use
|
||||
* thirdPartyPackageRegExp and standardPackageRegExp options.</p>
|
||||
* <pre>
|
||||
* <code>
|
||||
* <module name="CustomImportOrder">
|
||||
|
|
|
|||
|
|
@ -43,17 +43,87 @@ import com.puppycrawl.tools.checkstyle.checks.AbstractOptionCheck;
|
|||
* like non static imports (@see {@link ImportOrderOption}</li>
|
||||
* </ul>
|
||||
*
|
||||
* <pre>
|
||||
* Properties:
|
||||
* </pre>
|
||||
* <table summary="Properties" border="1">
|
||||
* <tr><th>name</th><th>Description</th><th>type</th><th>default value</th></tr>
|
||||
* <tr><td>option</td><td>policy on the relative order between regular imports and static
|
||||
* imports</td><td>{@link ImportOrderOption}</td><td>under</td></tr>
|
||||
* <tr><td>groups</td><td>list of imports groups (every group identified either by a common
|
||||
* prefix string, or by a regular expression enclosed in forward slashes (e.g. /regexp/)</td>
|
||||
* <td>list of strings</td><td>empty list</td></tr>
|
||||
* <tr><td>ordered</td><td>whether imports within group should be sorted</td>
|
||||
* <td>Boolean</td><td>true</td></tr>
|
||||
* <tr><td>separated</td><td>whether imports groups should be separated by, at least,
|
||||
* one blank line</td><td>Boolean</td><td>false</td></tr>
|
||||
* <tr><td>caseSensitive</td><td>whether string comparison should be case sensitive or not.
|
||||
* Case sensitive sorting is in ASCII sort order</td><td>Boolean</td><td>true</td></tr>
|
||||
* <tr><td>sortStaticImportsAlphabetically</td><td>whether static imports grouped by top or
|
||||
* bottom option are sorted alphabetically or not</td><td>Boolean</td><td>false</td></tr>
|
||||
* </table>
|
||||
*
|
||||
* <p>
|
||||
* Example:
|
||||
* </p>
|
||||
* <p>To configure the check so that it matches default Eclipse formatter configuration
|
||||
* (tested on Kepler, Luna and Mars):</p>
|
||||
* <ul>
|
||||
* <li>group of static imports is on the top</li>
|
||||
* <li>groups of non-static imports: "java" then "javax"
|
||||
* packages first, then "org" and then all other imports</li>
|
||||
* <li>imports will be sorted in the groups</li>
|
||||
* <li>groups are separated by, at least, one blank line</li>
|
||||
* </ul>
|
||||
*
|
||||
* <pre>
|
||||
* <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>
|
||||
* </pre>
|
||||
*
|
||||
* <p>To configure the check so that it matches default IntelliJ IDEA formatter configuration
|
||||
* (tested on v14):</p>
|
||||
* <ul>
|
||||
* <li>group of static imports is on the bottom</li>
|
||||
* <li>groups of non-static imports: all imports except of "javax" and
|
||||
* "java", then "javax" and "java"</li>
|
||||
* <li>imports will be sorted in the groups</li>
|
||||
* <li>groups are separated by, at least, one blank line</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* Note: "separated" option is disabled because IDEA default has blank line
|
||||
* between "java" and static imports, and no blank line between
|
||||
* "javax" and "java"
|
||||
* </p>
|
||||
*
|
||||
* <pre>
|
||||
* <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>
|
||||
* </pre>
|
||||
*
|
||||
* <p>To configure the check so that it matches default NetBeans formatter configuration
|
||||
* (tested on v8):</p>
|
||||
* <ul>
|
||||
* <li>groups of non-static imports are not defined, all imports will be sorted
|
||||
* as a one group</li>
|
||||
* <li>static imports are not separated, they will be sorted along with other imports</li>
|
||||
* </ul>
|
||||
*
|
||||
* <pre>
|
||||
* <module name="ImportOrder">
|
||||
* <property name="option" value="inflow"/>
|
||||
* </module>
|
||||
* </pre>
|
||||
*
|
||||
* <p>
|
||||
|
|
@ -72,18 +142,6 @@ import com.puppycrawl.tools.checkstyle.checks.AbstractOptionCheck;
|
|||
* </p>
|
||||
*
|
||||
* <p>
|
||||
* Defaults:
|
||||
* </p>
|
||||
* <ul>
|
||||
* <li>import groups: none</li>
|
||||
* <li>separation: false</li>
|
||||
* <li>ordered: true</li>
|
||||
* <li>case sensitive: true</li>
|
||||
* <li>static import: under</li>
|
||||
* <li>sort static imports alphabetically: false</li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* Check also has on option making it more flexible:
|
||||
* <b>sortStaticImportsAlphabetically</b> - sets whether static imports grouped by
|
||||
* <b>top</b> or <b>bottom</b> option should be sorted alphabetically or
|
||||
|
|
|
|||
|
|
@ -393,6 +393,10 @@ class FooBar {
|
|||
regular imports and static imports (see
|
||||
<a href="property_types.html#importOrder">import orders</a>)</li>
|
||||
</ul>
|
||||
<p>
|
||||
<a href="#ImportOrder_Example">Examples section</a> contains examples that
|
||||
work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Properties">
|
||||
|
|
@ -453,34 +457,71 @@ class FooBar {
|
|||
</table>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Example">
|
||||
<p>To configure the check so that it requires that:</p>
|
||||
<subsection name="Example" id="ImportOrder_Example">
|
||||
<p>To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler, Luna and Mars):</p>
|
||||
<ul>
|
||||
<li>"java" and "javax" packages together first, then "org" and then all other imports</li>
|
||||
<li>group of static imports is on the top</li>
|
||||
<li>groups of non-static imports: "java" then "javax" packages first, then "org" and then all other imports</li>
|
||||
<li>imports will be sorted in the groups</li>
|
||||
<li>groups are separated by, at least, one blank line</li>
|
||||
<li>static imports are above each local groups</li>
|
||||
</ul>
|
||||
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
<p>To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):</p>
|
||||
<ul>
|
||||
<li>group of static imports is on the bottom</li>
|
||||
<li>groups of non-static imports: all imports except of "javax" and "java", then "javax" and "java"</li>
|
||||
<li>imports will be sorted in the groups</li>
|
||||
<li>groups are separated by, at least, one blank line</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Note: "separated" option is disabled because IDEA default has blank line
|
||||
between "java" and static imports, and no blank line between
|
||||
"javax" and "java"
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
<p>To configure the check so that it matches default NetBeans formatter configuration (tested on v8):</p>
|
||||
<ul>
|
||||
<li>groups of non-static imports are not defined, all imports will be sorted as a one group</li>
|
||||
<li>static imports are not separated, they will be sorted along with other imports</li>
|
||||
</ul>
|
||||
|
||||
<source>
|
||||
<module name="ImportOrder">
|
||||
<property name="option" value="inflow"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure the Check allows static imports grouped to the <b>top</b>
|
||||
being sorted alphabetically:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
|
|
@ -572,7 +613,7 @@ public class SomeClass { ... }
|
|||
|
||||
<source>
|
||||
<module name="ImportControl">
|
||||
<property name="file" value="import-control.xml"/>
|
||||
<property name="file" value="import-control.xml"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
|
|
@ -584,9 +625,9 @@ public class SomeClass { ... }
|
|||
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
|
|
@ -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.
|
||||
</p>
|
||||
<p>
|
||||
<a href="#CustomImportOrder_Example">Examples section</a> contains examples that
|
||||
work with default formatter configurations of Eclipse, IntelliJ IDEA and NetBeans
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
<subsection name="RuleDescription">
|
||||
|
|
@ -720,7 +765,59 @@ public class SomeClass { ... }
|
|||
</table>
|
||||
</subsection>
|
||||
|
||||
<subsection name="Examples">
|
||||
<subsection name="Examples" id="CustomImportOrder_Example">
|
||||
<p>To configure the check so that it matches default Eclipse formatter configuration (tested on Kepler, Luna and Mars):</p>
|
||||
<ul>
|
||||
<li>group of static imports is on the top</li>
|
||||
<li>groups of non-static imports: "java" and "javax" packages first, then "org" and then all other imports</li>
|
||||
<li>imports will be sorted in the groups</li>
|
||||
<li>groups are separated by, at least, one blank line</li>
|
||||
</ul>
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
<p>To configure the check so that it matches default IntelliJ IDEA formatter configuration (tested on v14):</p>
|
||||
<ul>
|
||||
<li>group of static imports is on the bottom</li>
|
||||
<li>groups of non-static imports: all imports except of "javax" and "java", then "javax" and "java"</li>
|
||||
<li>imports will be sorted in the groups</li>
|
||||
<li>groups are separated by, at least, one blank line</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Note: "separated" option is disabled because IDEA default has blank line
|
||||
between "java" and static imports, and no blank line between
|
||||
"javax" and "java"
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<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>
|
||||
</source>
|
||||
|
||||
<p>To configure the check so that it matches default NetBeans formatter configuration (tested on v8):</p>
|
||||
<ul>
|
||||
<li>groups of non-static imports are not defined, all imports will be sorted as a one group</li>
|
||||
<li>static imports are not separated, they will be sorted along with other imports</li>
|
||||
</ul>
|
||||
|
||||
<source>
|
||||
<module name="CustomImportOrder"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To set RegExps for THIRD_PARTY_PACKAGE and STANDARD_JAVA_PACKAGE groups use
|
||||
thirdPartyPackageRegExp and standardPackageRegExp options.
|
||||
|
|
@ -728,7 +825,7 @@ public class SomeClass { ... }
|
|||
<source>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue