Issue #6749: aligned javadoc/xdoc for FileTabCharacter

checkstyle · May 13, 2019 · 17f6df3 · 17f6df3
1 parent 8431a3d
commit 17f6df3
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 6 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/whitespace/FileTabCharacterCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/whitespace/FileTabCharacterCheck.java
@@ -26,7 +26,50 @@
 import com.puppycrawl.tools.checkstyle.api.FileText;
 
 /**
- * Checks to see if a file contains a tab character.
+ * <p>
+ * Checks that there are no tab characters ({@code '\t'}) in the source code.
+ * </p>
+ * <p>
+ * Rationale:
+ * </p>
+ * <ul>
+ * <li>
+ * Developers should not need to configure the tab width of their text editors in order
+ * to be able to read source code.
+ * </li>
+ * <li>
+ * From the Apache jakarta coding standards: In a distributed development environment,
+ * when the commit messages get sent to a mailing list, they are almost impossible to
+ * read if you use tabs.
+ * </li>
+ * </ul>
+ * <ul>
+ * <li>
+ * Property {@code eachLine} - Control whether to report on each line containing a tab,
+ * or just the first instance.
+ * Default value is {@code false}.
+ * </li>
+ * <li>
+ * Property {@code fileExtensions} - Specify file type extension of files to process.
+ * Default value is {@code all files}.
+ * </li>
+ * </ul>
+ * <p>
+ * To configure the check to report on the first instance in each file:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;FileTabCharacter&quot;/&gt;
+ * </pre>
+ * <p>
+ * To configure the check to report on each line in each file:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;FileTabCharacter&quot;&gt;
+ *   &lt;property name=&quot;eachLine&quot; value=&quot;true&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ *
+ * @since 5.0
  */
 @StatelessCheck
 public class FileTabCharacterCheck extends AbstractFileSetCheck {
@@ -43,7 +86,7 @@ public class FileTabCharacterCheck extends AbstractFileSetCheck {
      */
     public static final String MSG_FILE_CONTAINS_TAB = "file.containsTab";
 
-    /** Indicates whether to report once per file, or for each line. */
+    /** Control whether to report on each line containing a tab, or just the first instance. */
     private boolean eachLine;
 
     @Override
@@ -66,7 +109,8 @@ protected void processFiltered(File file, FileText fileText) {
     }
 
     /**
-     * Whether report on each line containing a tab.
+     * Setter to control whether to report on each line containing a tab, or just the first
+     * instance.
      * @param eachLine Whether report on each line containing a tab.
      */
     public void setEachLine(boolean eachLine) {

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
@@ -93,6 +93,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         "EqualsHashCode",
         "ExplicitInitialization",
         "FallThrough",
+        "FileTabCharacter",
         "FinalClass",
         "FinalLocalVariable",
         "HiddenField",

diff --git a/src/xdocs/config_whitespace.xml b/src/xdocs/config_whitespace.xml
@@ -478,8 +478,8 @@ class Foo
     </section>
 
     <section name="FileTabCharacter">
+      <p>Since Checkstyle 5.0</p>
       <subsection name="Description" id="FileTabCharacter_Description">
-        <p>Since Checkstyle 5.0</p>
         <p>
           Checks that there are no tab characters (<code>'\t'</code>) in the source code.
         </p>
@@ -513,14 +513,16 @@ class Foo
           </tr>
           <tr>
             <td>eachLine</td>
-            <td>whether to report on each line containing a tab, or just the first instance</td>
+            <td>
+              Control whether to report on each line containing a tab, or just the first instance.
+            </td>
             <td><a href="property_types.html#boolean">Boolean</a></td>
             <td><code>false</code></td>
             <td>5.0</td>
           </tr>
           <tr>
             <td>fileExtensions</td>
-            <td>file type extension of files to process</td>
+            <td>Specify file type extension of files to process.</td>
             <td><a href="property_types.html#stringSet">String Set</a></td>
             <td><code>all files</code></td>
             <td>5.0</td>