Skip to content

Commit

Permalink
Issue checkstyle#6586: aligned javadoc/xdoc for DeclarationOrder
Browse files Browse the repository at this point in the history
  • Loading branch information
@pbludov
pbludov committed Mar 19, 2019
1 parent eb55ccf commit e5f8bd3
Show file tree
Hide file tree
Showing 3 changed files with 96 additions and 80 deletions.
144 changes: 78 additions & 66 deletions src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/DeclarationOrderCheck.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,80 +32,92 @@
import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;

/**
* Checks that the parts of a class or interface declaration
* appear in the order suggested by the
* <a href=
* "https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141855.html#1852">
* Code Conventions for the Java Programming Language</a>.
*
*
* <p>
* Checks the order in which parts of the class or interface declaration are defined.
* </p>
* <p>
* According to
* <a href="https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141855.html#1852">
* Code Conventions for the Java Programming Language</a>, the parts of a class
* or interface declaration should appear in the following order:
* </p>
* <ol>
* <li> Class (static) variables. First the public class variables, then
* the protected, then package level (no access modifier), and then
* the private. </li>
* <li>
* Class (static) variables. First the public class variables, then
* protected, then package level (no access modifier), and then private.
* </li>
* <li> Instance variables. First the public class variables, then
* the protected, then package level (no access modifier), and then
* the private. </li>
* protected, then package level (no access modifier), and then private.
* </li>
* <li> Constructors </li>
* <li> Methods </li>
* </ol>
*
* <p>
* Purpose of <b>ignore*</b> option is to ignore related violations,
* however it still impacts on other class members.
* </p>
* <p>ATTENTION: the check skips class fields which have
* <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.3.3">
* <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-8.html#jls-8.3.3">
* forward references </a> from validation due to the fact that we have Checkstyle's limitations
* to clearly detect user intention of fields location and grouping. For example,
* <pre>{@code
* public class A {
* private double x = 1.0;
* private double y = 2.0;
* public double slope = x / y; // will be skipped from validation due to forward reference
* }
* }</pre>
*
* <p>Available options:
* to clearly detect user intention of fields location and grouping. For example:
* </p>
* <pre>
* public class A {
* private double x = 1.0;
* private double y = 2.0;
* public double slope = x / y; // will be skipped from validation due to forward reference
* }
* </pre>
* <ul>
* <li>ignoreModifiers</li>
* <li>ignoreConstructors</li>
* <li>
* Property {@code ignoreConstructors} - control whether to ignore constructors.
* Default value is {@code false}.
* </li>
* <li>
* Property {@code ignoreModifiers} - control whether to ignore modifiers (fields, ...).
* Default value is {@code false}.
* </li>
* </ul>
*
* <p>Purpose of <b>ignore*</b> option is to ignore related violations,
* however it still impacts on other class members.
*
* <p>For example:
* <pre>{@code
* class K {
* int a;
* void m(){}
* K(){} &lt;-- "Constructor definition in wrong order"
* int b; &lt;-- "Instance variable definition in wrong order"
* }
* }</pre>
*
* <p>With <b>ignoreConstructors</b> option:
* <pre>{@code
* class K {
* int a;
* void m(){}
* K(){}
* int b; &lt;-- "Instance variable definition in wrong order"
* }
* }</pre>
*
* <p>With <b>ignoreConstructors</b> option and without a method definition in a source class:
* <pre>{@code
* class K {
* int a;
* K(){}
* int b; &lt;-- "Instance variable definition in wrong order"
* }
* }</pre>
*
* <p>An example of how to configure the check is:
*
* <p>
* To configure the check:
* </p>
* <pre>
* &lt;module name=&quot;DeclarationOrder&quot;/&gt;
* </pre>
* <p>
* With default options:
* </p>
* <pre>
* class K {
* int a;
* void m(){}
* K(){} &lt;-- &quot;Constructor definition in wrong order&quot;
* int b; &lt;-- &quot;Instance variable definition in wrong order&quot;
* }
* </pre>
* <p>
* With <b>ignoreConstructors</b> option:
* </p>
* <pre>
* class K {
* int a;
* void m(){}
* K(){}
* int b; &lt;-- &quot;Instance variable definition in wrong order&quot;
* }
* </pre>
* <p>
* With <b>ignoreConstructors</b> option and without a method definition in a source class:
* </p>
* <pre>
* &lt;module name="DeclarationOrder"/&gt;
* class K {
* int a;
* K(){}
* int b; &lt;-- &quot;Instance variable definition in wrong order&quot;
* }
* </pre>
*
* @since 3.2
*/
@FileStatefulCheck
public class DeclarationOrderCheck extends AbstractCheck {
Expand Down Expand Up @@ -155,9 +167,9 @@ public class DeclarationOrderCheck extends AbstractCheck {
/** Set of all class field names.*/
private Set<String> classFieldNames;

/** If true, ignores the check to constructors. */
/** Control whether to ignore constructors. */
private boolean ignoreConstructors;
/** If true, ignore the check to modifiers (fields, ...). */
/** Control whether to ignore modifiers (fields, ...). */
private boolean ignoreModifiers;

@Override
Expand Down Expand Up @@ -362,15 +374,15 @@ public void leaveToken(DetailAST ast) {
}

/**
* Sets whether to ignore constructors.
* Setter to control whether to ignore constructors.
* @param ignoreConstructors whether to ignore constructors.
*/
public void setIgnoreConstructors(boolean ignoreConstructors) {
this.ignoreConstructors = ignoreConstructors;
}

/**
* Sets whether to ignore modifiers.
* Setter to control whether to ignore modifiers (fields, ...).
* @param ignoreModifiers whether to ignore modifiers.
*/
public void setIgnoreModifiers(boolean ignoreModifiers) {
Expand Down
1 change: 1 addition & 0 deletions src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
"ConstantName",
"CovariantEquals",
"CustomImportOrder",
"DeclarationOrder",
"EmptyBlock",
"EmptyCatchBlock",
"EqualsAvoidNull",
Expand Down
31 changes: 17 additions & 14 deletions src/xdocs/config_coding.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -359,8 +359,11 @@ class Test {
</section>

<section name="DeclarationOrder">
<p>Since Checkstyle 3.2</p>
<subsection name="Description" id="DeclarationOrder_Description">
<p>Since Checkstyle 3.2</p>
<p>
Checks the order in which parts of the class or interface declaration are defined.
</p>
<p>
According to <a
href="https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141855.html#1852">
Expand Down Expand Up @@ -391,18 +394,18 @@ class Test {

<p>
ATTENTION: the check skips class fields which have
<a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.3.3">
<a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-8.html#jls-8.3.3">
forward references</a>
from validation due to the fact that we have Checkstyle's limitations to clearly
detect user intention of fields location and grouping. For example,
<source>
detect user intention of fields location and grouping. For example:
</p>
<source>
public class A {
private double x = 1.0;
private double y = 2.0;
public double slope = x / y; // will be skipped from validation due to forward reference
}
</source>
</p>
</source>
</subsection>

<subsection name="Properties" id="DeclarationOrder_Properties">
Expand All @@ -416,14 +419,14 @@ public class A {
</tr>
<tr>
<td>ignoreConstructors</td>
<td>whether to ignore constructors</td>
<td>control whether to ignore constructors.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
<td>5.2</td>
</tr>
<tr>
<td>ignoreModifiers</td>
<td>whether to ignore modifiers</td>
<td>control whether to ignore modifiers (fields, ...).</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
<td>5.2</td>
Expand All @@ -440,7 +443,8 @@ public class A {
</source>

<p>
For example:
With default options:
</p>
<source>
class K {
int a;
Expand All @@ -449,9 +453,9 @@ class K {
int b; &lt;-- "Instance variable definition in wrong order"
}
</source>
</p>
<p>
With <b>ignoreConstructors</b> option:
With <b>ignoreConstructors</b> option:
</p>
<source>
class K {
int a;
Expand All @@ -460,17 +464,16 @@ class K {
int b; &lt;-- "Instance variable definition in wrong order"
}
</source>
</p>
<p>
With <b>ignoreConstructors</b> option and without a method definition in a source class:
With <b>ignoreConstructors</b> option and without a method definition in a source class:
</p>
<source>
class K {
int a;
K(){}
int b; &lt;-- "Instance variable definition in wrong order"
}
</source>
</p>
</subsection>

<subsection name="Example of Usage" id="DeclarationOrder_Example_of_Usage">
Expand Down

0 comments on commit e5f8bd3

Please sign in to comment.