Issue checkstyle#7613: Update doc for MutableException

arinmodi · Nov 6, 2022 · 250582f · 250582f
1 parent b1c4475
commit 250582f
Show file tree

Hide file tree

Showing 2 changed files with 260 additions and 0 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/design/MutableExceptionCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/design/MutableExceptionCheck.java
@@ -66,6 +66,132 @@
  * <pre>
  * &lt;module name=&quot;MutableException&quot;/&gt;
  * </pre>
+ * <p>Example:</p>
+ * <pre>
+ * class FirstClass extends Exception {
+ *   private int code; // OK, Class-Name doesn't match with default pattern
+ *
+ *   public FirstClass() {
+ *     code = 1;
+ *   }
+ * }
+ *
+ * class MyException extends Exception {
+ *   private int code; // violation, The field 'code' must be declared final
+ *
+ *   public MyException() {
+ *     code = 2;
+ *   }
+ * }
+ *
+ * class MyThrowable extends Throwable {
+ *    final int code;
+ *    String message; // violation, The field 'message' must be declared final
+ *
+ *    public MyThrowable(int code, String message) {
+ *      this.code = code;
+ *      this.message = message;
+ *    }
+ * }
+ *
+ * class BadException extends java.lang.Exception {
+ *   int code; // violation, The field 'code' must be declared final
+ *
+ *   public BadException(int code) {
+ *     this.code = code;
+ *   }
+ * }
+ * </pre>
+ * <p>
+ * To configure the check so that it only checks for class names
+ * that match pattern:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;MutableException&quot;&gt;
+ *   &lt;property name=&quot;format&quot; value=&quot;^.*Exception$&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>Example:</p>
+ * <pre>
+ * class FirstClass extends Exception {
+ *   private int code; // OK, Class-Name doesn't match with Given pattern
+ *
+ *   public FirstClass() {
+ *     code = 1;
+ *   }
+ * }
+ *
+ * class MyException extends Exception {
+ *   private int code; // violation, The field 'code' must be declared final
+ *
+ *   public MyException() {
+ *     code = 2;
+ *   }
+ * }
+ *
+ * class MyThrowable extends Throwable {
+ *   final int code; // OK
+ *   String message; // OK
+ *
+ *   public MyThrowable(int code, String message) {
+ *     this.code = code;
+ *     this.message = message;
+ *   }
+ * }
+ *
+ * class BadException extends java.lang.Exception {
+ *   int code; // violation, The field 'code' must be declared final
+ *
+ *   public BadException(int code) {
+ *     this.code = code;
+ *   }
+ * }
+ * </pre>
+ * <p>
+ * To configure the check so that it only checks for type names used in 'extends'
+ * that match pattern:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;MutableException&quot;&gt;
+ *   &lt;property name=&quot;extendedClassNameFormat&quot; value=&quot;^.*Throwable$&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>Example:</p>
+ * <pre>
+ * class FirstClass extends Exception {
+ *   private int code; // OK, Extended-Class-Name doesn't match with Given pattern
+ *
+ *   public FirstClass() {
+ *     code = 1;
+ *   }
+ * }
+ *
+ * class MyException extends Exception {
+ *   private int code; // OK, Extended-Class-Name doesn't match with Given pattern
+ *
+ *   public MyException() {
+ *     code = 2;
+ *   }
+ * }
+ *
+ * class MyThrowable extends Throwable {
+ *   final int code; // OK
+ *   String message; // violation, The field 'message' must be declared final
+ *
+ *   public MyThrowable(int code, String message) {
+ *     this.code = code;
+ *     this.message = message;
+ *   }
+ * }
+ *
+ * class BadException extends java.lang.Exception {
+ *   int code; // OK, Extended-Class-Name doesn't match with Given pattern
+ *
+ *   public BadException(int code) {
+ *     this.code = code;
+ *   }
+ * }
+ * </pre>
  * <p>
  * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
  * </p>

diff --git a/src/xdocs/config_design.xml b/src/xdocs/config_design.xml
@@ -789,6 +789,140 @@ public interface Test2 { // violation
         <source>
 &lt;module name=&quot;MutableException&quot;/&gt;
         </source>
+        <p>Example:</p>
+        <div class="wrapper">
+          <source>
+class FirstClass extends Exception {
+  private int code; // OK, Class-Name doesn't match with default pattern
+
+  public FirstClass() {
+    code = 1;
+  }
+}
+
+class MyException extends Exception {
+  private int code; // violation, The field 'code' must be declared final
+
+  public MyException() {
+    code = 2;
+  }
+}
+
+class MyThrowable extends Throwable {
+  final int code;
+  String message; // violation, The field 'message' must be declared final
+
+  public MyThrowable(int code, String message) {
+    this.code = code;
+    this.message = message;
+  }
+}
+
+class BadException extends java.lang.Exception {
+  int code; // violation, The field 'code' must be declared final
+
+  public BadException(int code) {
+    this.code = code;
+  }
+}
+          </source>
+        </div>
+
+        <p>
+          To configure the check so that it only checks for class names
+          that match pattern:
+        </p>
+        <source>
+&lt;module name=&quot;MutableException&quot;&gt;
+  &lt;property name=&quot;format&quot; value=&quot;^.*Exception$&quot;/&gt;
+&lt;/module&gt;
+        </source>
+        <p>Example:</p>
+        <div class="wrapper">
+          <source>
+class FirstClass extends Exception {
+  private int code; // OK, Class-Name doesn't match with Given pattern
+
+  public FirstClass() {
+    code = 1;
+  }
+}
+
+class MyException extends Exception {
+  private int code; // violation, The field 'code' must be declared final
+
+  public MyException() {
+    code = 2;
+  }
+}
+
+class MyThrowable extends Throwable {
+  final int code; // OK
+  String message; // OK
+
+  public MyThrowable(int code, String message) {
+    this.code = code;
+    this.message = message;
+  }
+}
+
+class BadException extends java.lang.Exception {
+  int code; // violation, The field 'code' must be declared final
+
+  public BadException(int code) {
+    this.code = code;
+  }
+}
+          </source>
+        </div>
+
+        <p>
+          To configure the check so that it only checks for type names used in 'extends'
+          that match pattern:
+        </p>
+        <source>
+&lt;module name=&quot;MutableException&quot;&gt;
+  &lt;property name=&quot;extendedClassNameFormat&quot; value=&quot;^.*Throwable$&quot;/&gt;
+&lt;/module&gt;
+        </source>
+        <p>Example:</p>
+        <div class="wrapper">
+          <source>
+class FirstClass extends Exception {
+  private int code; // OK, Extended-Class-Name doesn't match with Given pattern
+
+  public FirstClass() {
+    code = 1;
+  }
+}
+
+class MyException extends Exception {
+  private int code; // OK, Extended-Class-Name doesn't match with Given pattern
+
+  public MyException() {
+    code = 2;
+  }
+}
+
+class MyThrowable extends Throwable {
+  final int code; // OK
+  String message; // violation, The field 'message' must be declared final
+
+  public MyThrowable(int code, String message) {
+    this.code = code;
+    this.message = message;
+  }
+}
+
+class BadException extends java.lang.Exception {
+  int code; // OK, Extended-Class-Name doesn't match with Given pattern
+
+  public BadException(int code) {
+    this.code = code;
+  }
+}
+          </source>
+        </div>
       </subsection>
 
       <subsection name="Example of Usage" id="MutableException_Example_of_Usage">