Issue checkstyle#6586: aligned javadoc/xdoc for EqualsAvoidNull

pbludov · Mar 18, 2019 · 7a527ae · 7a527ae
1 parent 4c559e1
commit 7a527ae
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 26 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/EqualsAvoidNullCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/EqualsAvoidNullCheck.java
@@ -29,33 +29,46 @@
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 /**
+ * <p>
  * Checks that any combination of String literals
- * is on the left side of an equals() comparison.
+ * is on the left side of an {@code equals()} comparison.
  * Also checks for String literals assigned to some field
  * (such as {@code someString.equals(anotherString = "text")}).
- *
- * <p>Rationale: Calling the equals() method on String literals
- * will avoid a potential NullPointerException.  Also, it is
- * pretty common to see null check right before equals comparisons
- * which is not necessary in the below example.
- *
- * <p>For example:
- *
+ * </p>
+ * <p>Rationale: Calling the {@code equals()} method on String literals
+ * will avoid a potential {@code NullPointerException}. Also, it is
+ * pretty common to see null checks right before equals comparisons,
+ * which is not necessary in the example below.
+ * </p>
+ * <p>
+ * For example, this code:
+ * </p>
  * <pre>
- *  {@code
- *    String nullString = null;
- *    nullString.equals(&quot;My_Sweet_String&quot;);
- *  }
+ * String nullString = null;
+ * nullString.equals(&quot;My_Sweet_String&quot;);
  * </pre>
- * should be refactored to
- *
+ * <p>
+ * should be refactored to:
+ * </p>
+ * <pre>
+ * String nullString = null;
+ * &quot;My_Sweet_String&quot;.equals(nullString);
+ * </pre>
+ * <ul>
+ * <li>
+ * Property {@code ignoreEqualsIgnoreCase} - Allow to ignore
+ * {@code String.equalsIgnoreCase(String)} invocations.
+ * Default value is {@code false}.
+ * </li>
+ * </ul>
+ * <p>
+ * To configure the check:
+ * </p>
  * <pre>
- *  {@code
- *    String nullString = null;
- *    &quot;My_Sweet_String&quot;.equals(nullString);
- *  }
+ * &lt;module name=&quot;EqualsAvoidNull&quot;/&gt;
  * </pre>
  *
+ * @since 5.0
  */
 @FileStatefulCheck
 public class EqualsAvoidNullCheck extends AbstractCheck {
@@ -81,7 +94,7 @@ public class EqualsAvoidNullCheck extends AbstractCheck {
     /** Curly for comparison. */
     private static final String LEFT_CURLY = "{";
 
-    /** Whether to process equalsIgnoreCase() invocations. */
+    /** Allow to ignore {@code String.equalsIgnoreCase(String)} invocations. */
     private boolean ignoreEqualsIgnoreCase;
 
     /** Stack of sets of field names, one for each class of a set of nested classes. */
@@ -120,7 +133,7 @@ public int[] getRequiredTokens() {
     }
 
     /**
-     * Whether to ignore checking {@code String.equalsIgnoreCase(String)}.
+     * Setter to allow to ignore {@code String.equalsIgnoreCase(String)} invocations.
      * @param newValue whether to ignore checking
      *    {@code String.equalsIgnoreCase(String)}.
      */

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
@@ -84,6 +84,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         "CustomImportOrder",
         "EmptyBlock",
         "EmptyCatchBlock",
+        "EqualsAvoidNull",
         "ImportOrder",
         "InterfaceMemberImpliedModifier",
         "InterfaceTypeParameterName",

diff --git a/src/xdocs/config_coding.xml b/src/xdocs/config_coding.xml
@@ -686,19 +686,19 @@ switch (i) {
     </section>
 
     <section name="EqualsAvoidNull">
+      <p>Since Checkstyle 5.0</p>
       <subsection name="Description" id="EqualsAvoidNull_Description">
-        <p>Since Checkstyle 5.0</p>
         <p>
           Checks that any combination of String literals
-          is on the left side of an equals() comparison.
+          is on the left side of an <code>equals()</code> comparison.
           Also checks for String literals assigned to some field
           (such as <code>someString.equals(anotherString = "text")</code>).
         </p>
 
         <p>
           Rationale: Calling the <code>equals()</code>
           method on String literals will avoid a potential
-          NullPointerException. Also, it is pretty common to see null
+          <code>NullPointerException</code>. Also, it is pretty common to see null
           checks right before equals comparisons, which is not necessary
           in the example below.
         </p>
@@ -730,9 +730,9 @@ String nullString = null;
           </tr>
           <tr>
             <td>ignoreEqualsIgnoreCase</td>
-            <td>whether to ignore <code>String.equalsIgnoreCase()</code> invocations</td>
+            <td>Allow to ignore <code>String.equalsIgnoreCase(String)</code> invocations.</td>
             <td><a href="property_types.html#boolean">Boolean</a></td>
-            <td>false</td>
+            <td><code>false</code></td>
             <td>5.4</td>
           </tr>
         </table>