Merge pull request #455 from felicity-semmle/java/SD-2779-qhelp-updates

Java: Update qhelp for queries with CWE tags (SD-2779)

Author: yh-semmle

java/ql/src/Violations of Best Practice/Dead Code/DeadStoreOfLocalUnread.qhelp

@@ -5,8 +5,9 @@
 
 
 <overview>
-<p>A value is assigned to a local variable, but the variable is never read subsequently. This means
-that the original assignment is suspect, because the state of the local variable that
+<p>A value is assigned to a local variable, but the local variable is only 
+read before the assignment, not after it.
+This means that the assignment is suspect, because the state of the local variable that
 it creates is never used.</p>
 
 </overview>
@@ -17,4 +18,6 @@ though: if the right-hand side has a side-effect (like performing a method call)
 it is important to keep this to preserve the overall behavior.</p>
 
 </recommendation>
+
+<include src="../../DeadCode/DeadCodeReferences.qhelp" />
 </qhelp>

java/ql/src/Violations of Best Practice/Dead Code/DeadStoreOfLocalUnread.ql

@@ -1,9 +1,6 @@
 /**
  * @name Useless assignment to local variable
- * @description A value is assigned to a local variable, but the local variable
- *              is only read before the assignment, not after it.
- *              The assignment has no effect: either it should be removed,
- *              or the assigned value should be used.
+ * @description Assigning a value to a local variable that is not later used has no effect.
  * @kind problem
  * @problem.severity recommendation
  * @precision low

java/ql/src/Violations of Best Practice/Dead Code/LocalInitialisedButNotUsed.qhelp

@@ -6,7 +6,7 @@
 
 <overview>
 <p>A local variable is initialized, but the variable is never read or written to subsequently. This suggests
-that the local variable is either useless and should be removed, or that the value was intended to be used
+that the local variable is either unnecessary and should be removed, or that the value was intended to be used
 somewhere.
 </p>
 
@@ -18,4 +18,7 @@ though: if the right-hand side has a side-effect (like performing a method call)
 it is important to keep this to preserve the overall behavior.</p>
 
 </recommendation>
+
+<include src="../../DeadCode/DeadCodeReferences.qhelp" />
+
 </qhelp>

java/ql/src/Violations of Best Practice/Dead Code/LocalInitialisedButNotUsed.ql

@@ -1,6 +1,6 @@
 /**
  * @name Local variable is initialized but not used
- * @description A local variable is initialized once, but never read or written to. Either the local variable is useless, or its value was intended to be used but is not.
+ * @description A local variable that is initialized but not subsequently used may indicate an error in the code.
  * @kind problem
  * @problem.severity recommendation
  * @precision low

java/ql/src/Violations of Best Practice/Dead Code/UnusedLocal.qhelp

@@ -5,26 +5,17 @@
 
 
 <overview>
-<p>A local variable that is never accessed nor initialized
-is typically a leftover from old refactorings or a sign of incomplete or pending
-code changes.</p>
+<p>A local variable that is not accessed or initialized
+is typically a sign of incomplete or pending code changes.</p>
 
 </overview>
 <recommendation>
 
-<p>If an unused variable is a leftover from old refactorings, you should just remove it. If it indicates
-incomplete or pending code changes, finish making the changes and remove the variable if it is not
+<p>If an unused variable is no longer needed following refactoring, you should just remove it. If there are
+incomplete or pending code changes, finish making the changes, and then remove the variable if it is no longer
 needed.</p>
 
 </recommendation>
-<references>
 
-
-<li>
-Help - Eclipse Platform:
-<a href="http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm">Java Compiler Errors/Warnings Preferences</a>.
-</li>
-
-
-</references>
+<include src="../../DeadCode/DeadCodeReferences.qhelp" />
 </qhelp>

java/ql/src/Violations of Best Practice/Dead Code/UnusedLocal.ql

@@ -1,6 +1,6 @@
 /**
  * @name Unused local variable
- * @description A local variable is entirely unused: it is not initialized, written to or read. The variable serves no purpose and obscures the code. It should be removed.
+ * @description A local variable that is not initialized, assigned, or read may indicate incomplete code.
  * @kind problem
  * @problem.severity recommendation
  * @precision low

java/ql/src/Violations of Best Practice/legacy/InexactVarArg.java

@@ -7,7 +7,7 @@ private static void length(Object... objects) {
 	public static void main(String[] args) {
 		String[] words = { "apple", "banana", "cherry" };
 		String[][] lists = { words, words };
-		length(words);	// BAD: Argument does not clarify
+		length(words);	// avoid: Argument does not clarify
 		length(lists);	// which parameter type is used.
 	}
 }

java/ql/src/Violations of Best Practice/legacy/InexactVarArg.qhelp

@@ -49,7 +49,7 @@ versions of Eclipse, the output may be:</p>
 
 <sample src="InexactVarArg.java" />
 
-<p>To fix the code, <code>length(words)</code> should be replaced by either of the following:</p>
+<p>To avoid this compiler-dependent behavior, <code>length(words)</code> should be replaced by either of the following:</p>
 
 <ul>
 <li><code>length((Object) words)</code></li>