Proofread Java inspections descriptions

GitOrigin-RevId: 09bc8b80c2b5c883f3657e2695291d4c58aca903
2026-09-27 10:03:11 +07:00 · 2021-06-22 15:37:07 +00:00
parent bf053a0156
commit dcaa222067
19 changed files with 107 additions and 107 deletions
@@ -1,6 +1,6 @@
 <html>
 <body>
-Reports any <code>boolean</code> expressions used twice that can be factorized, in order to reduce redundancy and improve the readability.
+Reports any <code>boolean</code> expressions used twice that can be factorized in order to reduce redundancy and improve readability of your code.
 <p><b>Example:</b></p>
 <pre><code>
  a &amp;&amp; b || a &amp;&amp; c
@@ -1,8 +1,8 @@
 <html>
 <body>
-Reports classes which do not have a logger declared.
-Ensuring that every class has a dedicated logger is an important step in providing a unified logging
-implementation for an application. Interfaces, enumerations, annotations, inner classes, and abstract classes are not reported by this inspection.
+Reports classes which do not have a declared logger.
+<p>Ensuring that every class has a dedicated logger is an important step in providing a unified logging
+  implementation for an application. Interfaces, enumerations, annotations, inner classes, and abstract classes are not reported by this inspection.</p>
 <p>For example:</p>
 <pre><code>
  <b>public class</b> NoLoggerDeclared {
@@ -15,8 +15,8 @@ implementation for an application. Interfaces, enumerations, annotations, inner
 </code></pre>
 <!-- tooltip end -->
 <p>
-Use the table below to specify logger class names.
-Classes which do not declare a field with the type of one of the classes specified, will be reported by this inspection.
+  Use the table in the <b>Options</b> section to specify logger class names.
+Classes which do not declare a field with the type of one of the specified classes will be reported by this inspection.

 </body>
 </html>
@@ -1,8 +1,8 @@
 <html>
 <body>
 Reports any instance fields which can be moved to a subclass.
-Because this inspection requires global code analysis it is only available for <em>Analyze|Inspect Code</em> or
-<em>Analyze|Run Inspection by Name</em> and it will not report in the editor.
+<p>Since this inspection requires a global code analysis, it is available only from <b>Code | Inspect Code</b> or
+  <b>Code | Analyze Code | Run Inspection by Name</b> and it will not report in the editor.</p>
 <!-- tooltip end -->
 <p>

@@ -1,20 +1,20 @@
 <html>
 <body>
-Reports the enhanced <code>for</code> statements.
-Such <code>for</code> statements are not supported under Java 1.4 and older.
+Reports enhanced <code>for</code> statements.
+Such <code>for</code> statements are not supported by Java of version 1.4 and older.
 <p>Example:</p>
-<pre>
+<pre><code>
  for (int x: Arrays.asList(1, 2, 3)) {
    System.out.println(x);
  }
-</pre>
-<p>After the quick-fix is applied, the result looks like this: </p>
-<pre>
+</code></pre>
+<p>After the quick-fix is applied: </p>
+<pre><code>
  for (Iterator&lt;Integer&gt; iterator = Arrays.asList(1, 2, 3).iterator(); iterator.hasNext(); ) {
    final int x = iterator.next();
    System.out.println(x);
  }
-</pre>
+</code></pre>
 <!-- tooltip end -->
 <p>

@@ -1,15 +1,16 @@
 <html>
 <body>
-Reports any <b>while</b>,
-<b>do-while</b> and <b>for</b>
-loops which have the constant <b>true</b> as their
-only condition, but which still can be terminated by a containing
-<b>if</b> statement which can break out of the loop.
-This <b>if</b> statement must be the first or only statement
-in a <b>while</b> or <b>for</b>
-loops and the last or only statement in a <b>do-while</b> loop.
-Such a loop would be clearer if the if statement was removed and its condition
-was made an explicit loop condition.
+Reports any <code>while</code>,
+<code>do-while</code>, and <code>for</code>
+loops that have the <code>true</code> constant as their
+only condition. At the same time, such loops can be still terminated by a containing
+<code>if</code> statement which can break out of the loop.
+<p>Such an <code>if</code> statement must be the first or the only statement
+in a <code>while</code> or <code>for</code>
+loop and the last or the only statement in a <code>do-while</code> loop.</p>
+
+<p>Removing the <code>if</code> statement and making its condition an explicit
+  loop condition simplifies the loop.</p>
 <!-- tooltip end -->
 <p>

@@ -1,9 +1,9 @@
 <html>
 <body>
-Reports "magic numbers", which are numeric literals used without being named by a constant declaration.
-Magic numbers can result in code whose intention is unclear, and may result in errors if a magic
-number is changed in one code location but not another. The numbers 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 100, 1000, 0L, 1L, 2L,
-0.0, 1.0, 0.0F and 1.0F are not reported by this inspection.
+Reports "magic numbers": numeric literals that are not named by a constant declaration.
+<p>Using magic numbers can lead to unclear code, as well as errors if a magic
+number is changed in one location but remains unchanged not another. The numbers 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 100, 1000, 0L, 1L, 2L,
+  0.0, 1.0, 0.0F and 1.0F are not reported by this inspection.</p>
 <p>Example:</p>
 <pre><code>
  void checkFileSize(long bytes) {
@@ -12,7 +12,7 @@ number is changed in one code location but not another. The numbers 0, 1, 2, 3,
    }
  }
 </code></pre>
-<p>A quick-fix is suggested to introduce a new constant:</p>
+<p>A quick-fix introduces a new constant:</p>
 <pre><code>
  static final int MAX_SUPPORTED_FILE_SIZE = 1_048_576;

@@ -23,15 +23,14 @@ number is changed in one code location but not another. The numbers 0, 1, 2, 3,
  }
 </code></pre>
 <!-- tooltip end -->
-<p>
-  Use the first checkbox below to disable this inspection within <code>hashCode()</code> methods.
-<p>
-  Use the second checkbox below to ignore magic numbers in annotations.
-<p>
-  Use the third checkbox below to ignore magic numbers used as initial capacity when constructing
-  <code>Collection</code>, <code>Map</code>,
-  <code>StringBuilder</code> or <code>StringBuffer</code> objects.
-<p>
+<p>Configure the inspection:</p>
+<ul>
+  <li>Use the <b>Ignore constants in 'hashCode()' methods</b> option to disable this inspection within <code>hashCode()</code> methods.</li>
+  <li>Use the <b>Ignore in annotations</b> option to ignore magic numbers in annotations.</li>
+  <li>Use the <b>Ignore initial capacity for StringBuilders and Collections</b> option to ignore magic numbers used as initial capacity when constructing
+    <code>Collection</code>, <code>Map</code>,
+    <code>StringBuilder</code> or <code>StringBuffer</code> objects.</li>
+</ul>

 </body>
 </html>
@@ -1,11 +1,11 @@
 <html>
 <body>
-Reports non-<code>exception</code> classes whose names end with '<code>Exception</code>'.
-Such classes may cause confusion by breaking a common naming convention, and
-are often the sign that developer forgot <code>extends Exception</code> clause.
+Reports non-<code>exception</code> classes whose names end with <code>Exception</code>.
+<p>Such classes may cause confusion by breaking a common naming convention and
+  often indicate that the <code>extends Exception</code> clause is missing.</p>
 <p><b>Example:</b>
  <pre><code>public class NotStartedException {}</code></pre>
-<p>Quick-fix to rename the class is suggested only in the editor..</p>
+<p>A quick-fix that renames such classes is available only in the editor.</p>
 <!-- tooltip end -->
 </body>
 </html>
@@ -1,18 +1,18 @@
 <html>
 <body>
 Reports any calls to overridden methods of the current class during object construction.
-A call is during object construction if it is inside:
+This happens if an object construction is inside:
 <ul>
-  <li>A Constructor</li>
-  <li>A Non-static instance initializer</li>
-  <li>A Non-static field initializer</li>
+  <li>A constructor</li>
+  <li>A non-static instance initializer</li>
+  <li>A non-static field initializer</li>
  <li><code>clone()</code></li>
  <li><code>readObject()</code></li>
  <li><code>readObjectNoData()</code></li>
 </ul>
-Such calls may result in subtle bugs, as the object is not guaranteed to be initialized before the method call occurs.
+<p>Such calls may result in subtle bugs, as the object is not guaranteed to be initialized before the method call occurs.</p>
 <p>Example:</p>
-<pre>
+<pre><code>
  abstract class Parent {
    void someMethod() { }
  }
@@ -25,13 +25,13 @@ Such calls may result in subtle bugs, as the object is not guaranteed to be init
    @Override
    void someMethod() { }
  }
-</pre>
+</code></pre>
 <!-- tooltip end -->
-This inspection shares functionality with:
+<p>This inspection shares its functionality with:</p>
 <ul>
-  <li>Abstract method called during object construction inspection</li>
-  <li>Overridable method called during object construction inspection</li>
+  <li>The <b>Abstract method called during object construction</b> inspection</li>
+  <li>The <b>Overridable method called during object construction</b> inspection</li>
 </ul>
-Only one inspection should be enabled at the same time to prevent duplicate warnings.
+<p>Only one inspection should be enabled at the same time to prevent duplicate warnings.</p>
 </body>
 </html>
@@ -1,23 +1,23 @@
 <html>
 <body>
 Reports any <code>package.html</code> files which are used for documenting packages.
-Since JDK 1.5 it is recommended to use <code>package-info.java</code> files instead, since such
-files can also contain package annotations. In this way, package-info.java becomes the
-sole repository for package level annotations and documentation.
+<p>Since JDK 1.5, it is recommended that you use <code>package-info.java</code> files instead, as such
+files can also contain package annotations. This way, package-info.java becomes a
+  sole repository for package level annotations and documentation.</p>
 <p>Example: <code>package.html</code></p>
-<pre>
+<pre><code>
 &lt;html&gt;
  &lt;body&gt;
    Documentation example.
  &lt;/body&gt;
 &lt;/html&gt;
-</pre>
-<p>After the quick-fix is applied, the result looks like this: <code>package-info.java</code></p>
-<pre>
+</code></pre>
+<p>After the quick-fix is applied: <code>package-info.java</code></p>
+<pre><code>
 /**
 * Documentation example.
 */
 package com.sample;
-</pre>
+</code></pre>
 </body>
 </html>
@@ -1,8 +1,8 @@
 <html>
 <body>
-Reports pointless comparison with
-<b>.indexOf()</b> expression. An example of such an expression
-is comparing the result of <b>.indexOf()</b> with numbers less than -1.
+Reports an unnecessary comparison with
+<code>.indexOf()</code> expression. An example of such an expression
+is comparing the result of <code>.indexOf()</code> with numbers smaller than -1.
 <!-- tooltip end -->
 <p>

@@ -1,16 +1,16 @@
 <html>
 <body>
-Reports usages of the Preview Feature API. The Preview Feature API is a set of elements that are annotated with <code>@PreviewFeature</code>.
+Reports usages of the Preview Feature API: a set of elements that are annotated with <code>@PreviewFeature</code>.
 <p>
  A preview feature is a new feature of the Java language, Java Virtual Machine, or Java SE API that is fully specified, fully implemented,
-  and yet impermanent. The notion of a preview feature is defined in <a href="https://openjdk.java.net/jeps/12">JEP 12</a>.
+  and is yet impermanent. The notion of a preview feature is defined in <a href="https://openjdk.java.net/jeps/12">JEP 12</a>.
 </p>
 <p>
-  If a code depends on a preview feature it might stop compiling in the future JDK versions if the feature get no positive feedback and,
-  hence, it either gets removed or changed.
+  If a piece of code depends on a preview feature, it might stop compiling in future JDK versions in case the feature gets no positive
+  feedback and gets removed or changed.
 </p>
 <!-- tooltip end -->
-<p>It's enabled only if the language level of the current project is a preview one.</p>
+<p>The inspection is enabled only if the language level of the current project is <b>Preview</b>.</p>
 <p><small>New in 2021.1</small></p>
 </body>
 </html>
@@ -1,8 +1,8 @@
 <html>
 <body>
-Reports modifiable <code>public</code> <code>static</code> Collection fields. Often used
-to store collections of constant values, these fields nonetheless represent a security
-hazard, as their contents may be modified, even if the field is declared as <code>final</code>.
+Reports modifiable <code>public</code> <code>static</code> Collection fields.
+<p>Even though they are often used to store collections of constant values, these fields nonetheless represent a security
+  hazard, as their contents may be modified even if the field is declared as <code>final</code>.</p>
 <p><b>Example:</b></p>
 <pre><code>
  public static final List&lt;String&gt; EVENTS = new ArrayList&lt;&gt;();
@@ -10,7 +10,7 @@ hazard, as their contents may be modified, even if the field is declared as <cod
 </pre>
 <!-- tooltip end -->
 <p>
-  Use the table below to specify methods returning unmodifiable collections.
-  <code>public</code> <code>static</code> Collection fields initialized with these methods will not be reported.
+  Use the table in the <b>Options</b> section to specify methods returning unmodifiable collections.
+  <code>public</code> <code>static</code> collection fields initialized with these methods will not be reported.
 </body>
 </html>
@@ -1,8 +1,8 @@
 <html>
 <body>
-<p>Inspection reports inheritors of Serializable, which 'serialVersionUID' differs from default generated one.</p>
+<p>Reports inheritors of Serializable whose <code>serialVersionUID</code> differs from the default generated ones.</p>
 <!-- tooltip end -->
-<p>This can happen when custom scheme for 'serialVersionUID' used or when something in class really changed since previous
-  'serialVersionUID' change which can lead to problems during deserialization.</p>
+<p>This can happen when you use a custom scheme for <code>serialVersionUID</code> or when something in the class changed since the previous
+  modification of <code>serialVersionUID</code>, which can lead to problems during deserialization.</p>
 </body>
 </html>
@@ -1,9 +1,10 @@
 <html>
 <body>
-Reports any static fields which are only used in a different class than the one they
-are defined in. Such fields can be moved.
-Because this inspection requires global code analysis it is only available for <em>Analyze|Inspect Code</em> or
-<em>Analyze|Run Inspection by Name</em> and it will not report in the editor.
+Reports any static fields that are used only in a class that is different from the one in which they
+are defined. Such fields can be moved.
+<p>
+Since this inspection requires a global code analysis, it is available only from <b>Code | Inspect Code</b> or
+  <b>Code | Analyze Code | Run Inspection by Name</b> and will not report in the editor.</p>
 <!-- tooltip end -->
 <p>

@@ -1,14 +1,16 @@
 <html>
 <body>
-Attempts to synchronize on an instance of a value-based class will produce compile-time warnings and raise run-time exceptions starting from Java 16.
+Reports attempts to synchronize on an instance of a value-based class that produce compile-time warnings and raise
+run-time exceptions starting from Java 16.
 <p>
-  For example, java.lang.Double is annotated with <code>jdk.internal.ValueBased</code>, so the following code will produce a compile-time warning
+  For example, <code>java.lang.Double</code> is annotated with <code>jdk.internal.ValueBased</code>, so the following code will
+  produce a compile-time warning:
 </p>
-<pre>
+<pre><code>
 Double d = 20.0;
 synchronized (d) { ... } // javac warning
-</pre>
+</code></pre>
 <!-- tooltip end -->
-<p>Since 2021.1</p>
+<p><small>New in 2021.1</small></p>
 </body>
 </html>
@@ -1,9 +1,9 @@
 <html>
 <body>
-Reports non-<code>abstract</code> test cases which do not
-contain any test methods. Such test cases usually indicate unfinished code,
-or could be a refactoring leftover that should be removed.
-<p>For example:</p>
+Reports non-<code>abstract</code> test cases without any test methods.
+<p>Such test cases usually indicate unfinished code
+  or could be a refactoring leftover that should be removed.</p>
+<p>Example:</p>
 <pre><code>
  <b>public class</b> CrucialTest {
    @Before
@@ -13,10 +13,8 @@ or could be a refactoring leftover that should be removed.
  }
 </code></pre>
 <!-- tooltip end -->
-<p>
-Use the checkbox below to specify that test cases which have super classes with
-test methods should be ignored by this inspection.
-<p>
+<p>Use the <b>Ignore test cases which have superclasses with test methods</b> option to ignore test cases which have super classes
+  with test methods.<p>

 </body>
 </html>
@@ -1,8 +1,9 @@
 <html>
 <body>
-Reports <code>throw</code> statements inside of <code>finally</code>
-blocks. While occasionally intended, such <code>throw</code> statements may mask exceptions thrown from <code>try</code>-<code>catch</code> and thus
-tremendously complicate debugging.
+Reports <code>throw</code> statements inside <code>finally</code>
+blocks.
+<p>While occasionally intended, such <code>throw</code> statements may conceal exceptions thrown from <code>try</code>-<code>catch</code> and thus
+  tremendously complicate the debugging process.</p>
 <!-- tooltip end -->
 <p>

@@ -1,7 +1,7 @@
 <html>
 <body>
-Reports uses of concrete classes, rather than interfaces.
-Such declarations may represent a failure of abstraction, and may make testing more difficult.
+Reports usages of concrete classes, rather than interfaces.
+Such declarations may represent a failure of abstraction and may make testing more difficult.
 <p>
 Declarations whose classes come from system or third-party libraries will not be reported by this inspection.
 Casts, instanceofs, and local variables are not reported in <code>equals()</code> method implementations.
@@ -26,8 +26,7 @@ Also, casts are not reported in <code>clone()</code> method implementations.
 </code></pre>
 <!-- tooltip end -->
 <p>
-  Use the first checkbox below to ignore casts to abstract classes.</p>
-<p>
-  Use the subsequent checkboxes to control contexts where the problem is reported.</p>
+  Use the <b>Ignore abstract class type</b> option to ignore casts to abstract classes.</p>
+<p>Use the subsequent options to control contexts where the problem is reported.</p>
 </body>
 </html>
@@ -1,9 +1,8 @@
 <html>
 <body>
-Reports any uses of <b>java.util.Date</b>, <b>java.util.Calendar</b>, <b>java.util.GregorianCalendar</b>, <b>java.util.TimeZone</b>,
-and <b>java.util.SimpleTimeZone</b>.
-While still supported, these classes were made obsolete by the JDK8 Date-Time API, and should probably
-not be used in new development.
+Reports usages of <code>java.util.Date</code>, <code>java.util.Calendar</code>, <code>java.util.GregorianCalendar</code>, <code>java.util.TimeZone</code>,
+and <code>java.util.SimpleTimeZone</code>.
+<p>While still supported, these classes have been obsolete since JDK8 Date-Time API and should not be used in new development.</p>
 <!-- tooltip end -->
 <p>