Issue checkstyle#7642: Update doc for IllegalCatch

wltan · Mar 10, 2020 · 37b2a14 · 37b2a14
1 parent ddc7f5b
commit 37b2a14
Show file tree

Hide file tree

Showing 2 changed files with 148 additions and 0 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/IllegalCatchCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/IllegalCatchCheck.java
@@ -56,7 +56,79 @@
  * <pre>
  * &lt;module name=&quot;IllegalCatch&quot;/&gt;
  * </pre>
+ * <p>Example:</p>
+ * <pre>
+ * try {
+ *     // some code here
+ * } catch (Exception e) { // violation
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (ArithmeticException e) { // OK
+ *
+ * } catch (Exception e) { // violation, catching Exception is illegal
+ *                           and order of catch blocks doesn't matter
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (ArithmeticException | Exception e) { // violation, catching Exception is illegal
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (ArithmeticException e) { // OK
  *
+ * }
+ *
+ * </pre>
+ * <p>
+ * To configure the check to override the default list
+ * with ArithmeticException and OutOfMemoryError:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;IllegalCatch&quot;&gt;
+ *   &lt;property name=&quot;illegalClassNames&quot; value=&quot;ArithmeticException,
+ *               OutOfMemoryError&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>Example:</p>
+ * <pre>
+ * try {
+ *     // some code here
+ * } catch (OutOfMemoryError e) { // violation
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (ArithmeticException e) { // violation
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (NullPointerException e) { // OK
+ *
+ * } catch (OutOfMemoryError e) { // violation
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (ArithmeticException | Exception e) {  // violation
+ *
+ * }
+ *
+ * try {
+ *     // some code here
+ * } catch (Exception e) { // OK
+ *
+ * }
+ * </pre>
  * @since 3.2
  */
 @StatelessCheck

diff --git a/src/xdocs/config_coding.xml b/src/xdocs/config_coding.xml
@@ -1808,6 +1808,82 @@ class SomeClass
         <source>
 &lt;module name=&quot;IllegalCatch&quot;/&gt;
         </source>
+          <p>
+              Example:
+          </p>
+        <source>
+try {
+    // some code here
+} catch (Exception e) { // violation
+
+}
+
+try {
+    // some code here
+} catch (ArithmeticException e) { // OK
+
+} catch (Exception e) { // violation, catching Exception is illegal
+                          and order of catch blocks doesn't matter
+}
+
+try {
+    // some code here
+} catch (ArithmeticException | Exception e) { // violation, catching Exception is illegal
+
+}
+
+try {
+    // some code here
+} catch (ArithmeticException e) { // OK
+
+}
+          </source>
+          <p>
+              To configure the check to override the default list with
+              ArithmeticException and OutOfMemoryError:
+          </p>
+          <source>
+&lt;module name=&quot;IllegalCatch&quot;&gt;
+  &lt;property name=&quot;illegalClassNames&quot; value=&quot;ArithmeticException,
+              OutOfMemoryError&quot;/&gt;
+&lt;/module&gt;
+          </source>
+          <p>
+              Example:
+          </p>
+          <source>
+try {
+    // some code here
+} catch (OutOfMemoryError e) { // violation
+
+}
+
+try {
+    // some code here
+} catch (ArithmeticException e) { // violation
+
+}
+
+try {
+    // some code here
+} catch (NullPointerException e) { // OK
+
+} catch (OutOfMemoryError e) { // violation
+
+}
+
+try {
+    // some code here
+} catch (ArithmeticException | Exception e) {  // violation
+
+}
+
+try {
+    // some code here
+} catch (Exception e) { // OK
+
+}
+          </source>
       </subsection>
 
       <subsection name="Example of Usage" id="IllegalCatch_Example_of_Usage">