Issue #6586: aligned javadoc/xdoc for NoFinalizer

checkstyle · Apr 22, 2019 · f7626ac · f7626ac
1 parent 40c3c3f
commit f7626ac
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 3 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/NoFinalizerCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/NoFinalizerCheck.java
@@ -25,9 +25,28 @@
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 /**
- * Checks that no method having zero parameters is defined
- * using the name <em>finalize</em>.
+ * <p>
+ * Verifies there are no {@code finalize()} methods defined in a class.
+ * </p>
+ * <p>
+ * See
+ * <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html#finalize()">
+ * Object.finalize()</a>
+ * </p>
+ * <p>
+ * Rationale: Finalizers are unpredictable, often dangerous, and generally unnecessary.
+ * Their use can cause erratic behavior, poor performance, and portability problems.
+ * For more information for the finalize method and its issues, see Effective Java:
+ * Programming Language Guide Third Edition by Joshua Bloch, &#167;8.
+ * </p>
+ * <p>
+ * To configure the check:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;NoFinalizer&quot;/&gt;
+ * </pre>
  *
+ * @since 5.0
  */
 @StatelessCheck
 public class NoFinalizerCheck extends AbstractCheck {

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
@@ -124,6 +124,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         "NestedIfDepth",
         "NestedTryDepth",
         "NoClone",
+        "NoFinalizer",
         "OneStatementPerLine",
         "OverloadMethodsDeclarationOrder",
         "PackageAnnotation",

diff --git a/src/xdocs/config_coding.xml b/src/xdocs/config_coding.xml
@@ -3497,12 +3497,22 @@ System.out.println(s2 instanceof Square); //true
     </section>
 
     <section name="NoFinalizer">
+      <p>Since Checkstyle 5.0</p>
       <subsection name="Description" id="NoFinalizer_Description">
-        <p>Since Checkstyle 5.0</p>
         <p>
           Verifies there are no <code>finalize()</code> methods
           defined in a class.
         </p>
+        <p>
+          See <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Object.html#finalize()">
+          Object.finalize()</a>
+        </p>
+        <p>
+            Rationale: Finalizers are unpredictable, often dangerous, and generally unnecessary.
+            Their use can cause erratic behavior, poor performance, and portability problems.
+            For more information for the finalize method and its issues, see Effective Java:
+            Programming Language Guide Third Edition by Joshua Bloch, &#167;8.
+        </p>
       </subsection>
 
       <subsection name="Examples" id="NoFinalizer_Examples">