[java] improve inspection description

GitOrigin-RevId: 390d649e3c9b19faf34586db088470a34e869bd2
2026-09-27 10:03:11 +07:00 · 2021-03-16 19:11:03 +00:00
parent ad7bb1b277
commit 8de25cdb46
7 changed files with 88 additions and 23 deletions
@@ -1,10 +1,27 @@
 <html>
 <body>
-Reports when <strong>list.remove(index)</strong> is called inside the ascending counted loop. This is suspicious as list becomes
-shorter after that and the element next to removed will not be processed. Simple fix is to decrease the index variable after removal,
-but probably removing via iterator or using <strong>removeIf</strong> method (since Java 8) is a more robust alternative.
-If you don't expect that <strong>remove</strong> will be called more than once in a loop, consider adding a <strong>break</strong> command
-after it.
+Reports when <code>list.remove(index)</code> is called inside the ascending counted loop. This is suspicious as list becomes
+shorter after that, and the element next to removed will not be processed. A simple fix is to decrease the index variable after removal,
+but probably removing via iterator or using <code>removeIf</code> method (since Java 8) is a more robust alternative.
+If you don't expect that <code>remove</code> will be called more than once in a loop, consider adding a <code>break</code> after it.
+
+<p>Example:</p>
+<pre>
+  public static void main(String[] args) {
+    process(new ArrayList<>(Arrays.asList("1", "2", "|", "3", "4")));
+  }
+
+  static void process(List&ltString&gt list) {
+    for (int i = 0; i < list.size(); i++) {
+      if (list.get(i).equals("|")) {
+        list.remove(i);
+        continue;
+      }
+      System.out.println(list.get(i));
+    }
+  }
+</pre>
+<p>Here we could expect that '1 2 3 4' will be printed, but 3 will be skipped in the output.</p>
 <!-- tooltip end -->
 <p><small>New in 2018.2</small></p>
 </body>
@@ -1,9 +1,17 @@
 <html>
 <body>
-Reports cases where the argument of a method call on a <b>java.util.Collection</b>
-or <b>java.util.Map</b> is the collection or map itself.
-This includes adding a collection to itself, which can lead to a <b>java.lang.StackOverflowError</b> when,
-for example, calling <b>hashCode()</b> on the self-containing collection.
+Reports cases where the argument of a method call on a <code>java.util.Collection</code>
+or <code>java.util.Map</code> is the collection or map itself.
+This includes adding a collection to itself, which can lead to a <code>java.lang.StackOverflowError</code> when,
+for example, calling <code>hashCode()</code> on the self-containing collection.
+May happen in the code with raw types as a result of copy-paste.
+
+<p>Example:</p>
+<pre>
+  ArrayList list = new ArrayList<>();
+  list.add(list);
+  return list.hashCode(); // throws StackOverflowException
+</pre>
 <!-- tooltip end -->
 <p>

@@ -1,10 +1,19 @@
 <html>
 <body>
 Reports any calls to
-<b>String.replaceAll()</b> or <b>String.split()</b> where the first argument is a single regex meta character argument.
+<code>String.replaceAll()</code> or <code>String.split()</code> where the first argument is a single regex meta character argument.
 The regex meta characters are one of ".$|()[{^?*+\", and these have a special meaning in regular expressions.
-For example calling <b>"ab.cd".replaceAll(".", "-")</b> produces <b>"-----"</b>, because the dot matches any character.
-Most likely the escaped variant <b>"\\."</b> was intended instead.
+For example calling <code>"ab.cd".replaceAll(".", "-")</code> produces <code>"-----"</code>, because the dot matches any character.
+Most likely the escaped variant <code>"\\."</code> was intended instead.
+
+<p>Example:</p>
+<pre>
+  s.replaceAll(".", "-");
+</pre>
+<p>After the quick-fix is applied the result looks like:</p>
+<pre>
+  s.replaceAll("\\.", "-");
+</pre>
 <!-- tooltip end -->
 <p>

@@ -1,7 +1,7 @@
 <html>
 <body>
-Reports any calls to <b>run()</b> on <b>java.lang.Thread</b> or any of its subclasses.
-While occasionally intended, this is usually a mistake, with <b>start()</b> intended instead.
+Reports any calls to <code>run()</code> on <code>java.lang.Thread</code> or any of its subclasses because <code>run()</code> doesn't start a new thread.
+While occasionally intended, this is usually a mistake, with <code>start()</code> intended instead.
 <!-- tooltip end -->
 <p>

@@ -1,9 +1,16 @@
 <html>
 <body>
-Reports instantiations of <b>Throwable</b> and subclasses, where the created <b>Throwable</b>
-is never actually thrown. Also reports method calls which return <b>Throwable</b> instances,
+Reports instantiations of <code>Throwable</code> and subclasses, where the created <code>Throwable</code>
+is never actually thrown. Also reports method calls which return <code>Throwable</code> instances,
 where the result of the method call is not thrown. These are simple mistakes to make which
 are hard to catch in tests.
+<p>Example:</p>
+<pre>
+    void leftBehind() throws Throwable {
+        RuntimeException e = new RuntimeException("throw me");
+        // ...
+    }
+</pre>
 <!-- tooltip end -->
 <p>

@@ -1,12 +1,36 @@
 <html>
 <body>
-Reports enum <b>switch</b> statements or expression with <b>default</b> branches which can never be taken,
-because all possible values are covered by a <b>case</b> branch.
-These are unnecessary, especially for <b>switch</b> expressions, because they don't compile when all
-<b>enum</b> constants are not covered by a <b>case</b> branch.
+Reports enum <code>switch</code> statements or expression with <code>default</code> branches which can never be taken,
+because all possible values are covered by a <code>case</code> branch.
+These are unnecessary, especially for <code>switch</code> expressions, because they don't compile when all
+<b>enum</b> constants are not covered by a <code>case</code> branch.
 <p>
-  The language level needs to be configured to 13 Preview to report <b>switch</b> expressions.
+  The language level needs to be configured to 13 Preview to report <code>switch</code> expressions.
+</p>
+Quick fix removes default branch.
+<p>Example:</p>
+<pre>
+  enum E { A, B }
+  int foo(E e) {
+    return = switch (e) {
+      case A -> 1;
+      case B -> 2;
+      default -> 3;
+    };
+  }
+</pre>
+<p>After the quick-fix is applied the result looks like:</p>
+<pre>
+  enum E { A, B }
+  int foo(E e) {
+    return = switch (e) {
+      case A -> 1;
+      case B -> 2;
+    };
+  }
+</pre>
 <!-- tooltip end -->
+<p>Use option to report only unnecessary default branches in switch expressions</p>
 <p>

 </body>
@@ -1,6 +1,6 @@
 <html>
 <body>
-Inspection checks that method which is marked with <b>@DataProvider</b> annotation
-returns <b>Object[][]</b> or <b>Iterator&lt;Object&gt;</b>.
+Reports methods marked with <code>@DataProvider</code> annotation which returns not <code>Object[][]</code> or <code>Iterator&lt;Object&gt;</code>.
+If other type is returned, TestNG will throw an exception.
 </body>
 </html>