Issue checkstyle#6966: aligned javadoc/xdoc for TodoComment

pbludov · Aug 24, 2019 · 3afa203 · 3afa203
1 parent e1bb6ef
commit 3afa203
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 15 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/TodoCommentCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/TodoCommentCheck.java
@@ -28,26 +28,37 @@
 
 /**
  * <p>
- * A check for 'TODO:' comments. To check for other patterns in Java comments, set
- * property format.
+ * A check for {@code TODO:} comments. Actually it is a generic
+ * <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html">
+ * regular expression</a> matcher on Java comments. To check for other patterns
+ * in Java comments, set the {@code format} property.
  * </p>
  * <p>
- * An example of how to configure the check is:
+ * Using {@code TODO:} comments is a great way to keep track of tasks that need to be done.
+ * Having them reported by Checkstyle makes it very hard to forget about them.
+ * </p>
+ * <ul>
+ * <li>
+ * Property {@code format} - Specify pattern to match comments against.
+ * Default value is {@code "TODO:"}.
+ * </li>
+ * </ul>
+ * <p>
+ * To configure the check:
  * </p>
- *
  * <pre>
  * &lt;module name="TodoComment"/&gt;
  * </pre>
  * <p>
- * An example of how to configure the check for comments that contain
- * {@code TODO} or {@code FIXME}is:
+ * To configure the check for comments that contain {@code TODO} and {@code FIXME}:
  * </p>
- *
  * <pre>
  * &lt;module name="TodoComment"&gt;
- *    &lt;property name="format" value="(TODO)|(FIXME)"/&gt;
+ *   &lt;property name="format" value="(TODO)|(FIXME)"/&gt;
  * &lt;/module&gt;
  * </pre>
+ *
+ * @since 3.0
  */
 @StatelessCheck
 public class TodoCommentCheck
@@ -60,7 +71,7 @@ public class TodoCommentCheck
     public static final String MSG_KEY = "todo.match";
 
     /**
-     * Regular expression pattern compiled from format.
+     * Specify pattern to match comments against.
      */
     private Pattern format = Pattern.compile("TODO:");
 
@@ -70,7 +81,7 @@ public boolean isCommentNodesRequired() {
     }
 
     /**
-     * Setter for 'todo' comment pattern.
+     * Setter to specify pattern to match comments against.
      * @param pattern
      *        pattern of 'todo' comment.
      */

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
@@ -100,7 +100,6 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         // miscellaneous
         "Indentation",
         "NewlineAtEndOfFile",
-        "TodoComment",
         // modifier
         "AnonInnerLength",
         "ExecutableStatementCount",

diff --git a/src/xdocs/config_misc.xml b/src/xdocs/config_misc.xml
@@ -1534,12 +1534,13 @@ key.png =value - violation
     </section>
 
     <section name="TodoComment">
+      <p>Since Checkstyle 3.0</p>
       <subsection name="Description" id="TodoComment_Description">
-        <p>Since Checkstyle 3.0</p>
         <p>
           A check for <code>TODO:</code> comments. Actually
-          it is a generic <a
-          href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular
+          it is a generic
+          <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html">
+          regular
           expression</a> matcher on Java comments. To check for other
           patterns in Java comments, set the <code>format</code> property.
         </p>
@@ -1556,7 +1557,7 @@ key.png =value - violation
           </tr>
           <tr>
             <td>format</td>
-            <td>Pattern to match comments against</td>
+            <td>Specify pattern to match comments against.</td>
             <td><a href="property_types.html#regexp">Regular Expression</a></td>
             <td><code>"TODO:"</code></td>
             <td>3.0</td>