Merge pull request #20052 from joefarebrother/python-qual-minor-doc-updates

Python: Minor documantation updates to several quality queries

Author: joefarebrother

python/ql/src/Exceptions/CatchingBaseException.qhelp

@@ -45,10 +45,10 @@ leaving <code>KeyboardInterrupt</code> to propagate.
 </example>
 <references>
 
-<li>Python Language Reference: <a href="http://docs.python.org/2.7/reference/compound_stmts.html#try">The try statement</a>, 
-<a href="http://docs.python.org/2.7/reference/executionmodel.html#exceptions">Exceptions</a>.</li>
+<li>Python Language Reference: <a href="http://docs.python.org/3/reference/compound_stmts.html#try">The try statement</a>, 
+<a href="http://docs.python.org/3/reference/executionmodel.html#exceptions">Exceptions</a>.</li>
 <li>M. Lutz, Learning Python, Section 35.3: Exception Design Tips and Gotchas, O'Reilly Media, 2013.</li>
-<li>Python Tutorial: <a href="https://docs.python.org/2/tutorial/errors.html">Errors and Exceptions</a>.</li>
+<li>Python Tutorial: <a href="https://docs.python.org/3/tutorial/errors.html">Errors and Exceptions</a>.</li>
 
 
 </references>

python/ql/src/Exceptions/EmptyExcept.qhelp

@@ -7,15 +7,15 @@
 The loss of information can lead to hard to debug errors and incomplete log files.
 It is even possible that ignoring an exception can cause a security vulnerability.
 An empty <code>except</code> block may be an indication that the programmer intended to
-handle the exception but never wrote the code to do so.</p>
+handle the exception, but never wrote the code to do so.</p>
 
 </overview>
 <recommendation>
 <p>Ensure all exceptions are handled correctly.</p>
 
 </recommendation>
 <example>
-<p>In this example the program keeps running with the same privileges if it fails to drop to lower 
+<p>In this example, the program keeps running with the same privileges if it fails to drop to lower 
 privileges.</p>
 <sample src="EmptyExcept.py" />
 

python/ql/src/Expressions/CallToSuperWrongClass.qhelp

@@ -24,7 +24,7 @@ However, this may result in incorrect object initialization if the enclosing cla
 </recommendation>
 <example>
 <p>
-In this example the call to <code>super(Vehicle, self)</code> in <code>Car.__init__</code> is incorrect as it
+In this example, the call to <code>super(Vehicle, self)</code> in <code>Car.__init__</code> is incorrect, as it
 passes <code>Vehicle</code> rather than <code>Car</code> as the first argument to <code>super</code>.
 As a result, <code>super(SportsCar, self).__init__()</code> in the <code>SportsCar.__init__</code> method will not call
 all <code>__init__()</code> methods because the call to <code>super(Vehicle, self).__init__()</code>
@@ -37,7 +37,7 @@ skips <code>StatusSymbol.__init__()</code>.
 </example>
 <references>
 
-    <li>Python Standard Library: <a href="https://docs.python.org/2/library/functions.html#super">super</a>.</li>
+    <li>Python Standard Library: <a href="https://docs.python.org/3/library/functions.html#super">super</a>.</li>
     <li>Artima Developer: <a href="http://www.artima.com/weblogs/viewpost.jsp?thread=236275">Things to Know About Python Super</a>.</li>
 
 

python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.py

@@ -1,2 +1,2 @@
-dictionary = {1:"a", 2:"b", 2:"c"}
-print dictionary[2]
+dictionary = {1:"a", 2:"b", 2:"c"} # BAD: The `2` key is duplicated.
+print(dictionary[2])

python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.qhelp

@@ -4,8 +4,8 @@
 <qhelp>
 <overview>
 <p>Dictionary literals are constructed in the order given in the source.
-This means that if a key is duplicated the second key-value pair will overwrite
-the first as a dictionary can only have one value per key.
+This means that if a key is duplicated, the second key-value pair will overwrite
+the first; as a dictionary can only have one value per key.
 </p>
 
 </overview>
@@ -15,14 +15,14 @@ If they are then decide which value is wanted and delete the other one.</p>
 
 </recommendation>
 <example>
-<p>This example will output "c" because the mapping between 2 and "b" is overwritten by the
-mapping from 2 to "c". The programmer may have meant to map 3 to "c" instead.</p>
+<p>The following example will output <code>"c"</code>, because the mapping between 2 and <code>"b"</code> is overwritten by the
+mapping from 2 to <code>"c"</code>. The programmer may have meant to map 3 to <code>"c"</code> instead.</p>
 <sample src="DuplicateKeyInDictionaryLiteral.py" />
 
 </example>
 <references>
 
-  <li>Python: <a href="http://docs.python.org/2/reference/expressions.html#dictionary-displays">Dictionary literals</a>.</li>
+  <li>Python: <a href="http://docs.python.org/3/reference/expressions.html#dictionary-displays">Dictionary literals</a>.</li>
 
 </references>
 </qhelp>

python/ql/src/Expressions/ExplicitCallToDel.qhelp

@@ -17,7 +17,7 @@ wrap the use of the object in a <code>with</code> statement.
 
 </recommendation>
 <example>
-<p>In the first example, rather than close the zip file in a conventional manner the programmer has called <code>__del__</code>.
+<p>In the first example, rather than close the zip file in a conventional manner, the programmer has called <code>__del__</code>.
 A safer alternative is shown in the second example.
 </p>
 

python/ql/src/Expressions/IncorrectComparisonUsingIs.qhelp

@@ -37,7 +37,7 @@ either of the alternatives below.
 </example>
 <references>
 
-     <li>Python Standard Library: <a href="http://docs.python.org/2/library/stdtypes.html#comparisons">Comparisons</a>.</li>
+     <li>Python Standard Library: <a href="http://docs.python.org/3/library/stdtypes.html#comparisons">Comparisons</a>.</li>
 
 </references>
 </qhelp>

python/ql/src/Expressions/IncorrectComparisonUsingIs.ql

@@ -1,6 +1,6 @@
 /**
  * @name Comparison using is when operands support `__eq__`
- * @description Comparison using 'is' when equivalence is not the same as identity
+ * @description Comparison using `is` when equivalence is not the same as identity
  * @kind problem
  * @tags quality
  *       reliability

python/ql/src/Expressions/UnsupportedFormatCharacter.qhelp

@@ -3,26 +3,27 @@
   "qhelp.dtd">
 <qhelp>
 <overview>
-<p>A format string, that is the string on the left hand side of an expression like <code>fmt % arguments</code>, must consist of legal conversion specifiers.
+<p>A printf-style format string (i.e. a string that is used as the left hand side of the <code>%</code> operator, such as <code>fmt % arguments</code>)
+must consist of valid conversion specifiers, such as <code>%s</code>, <code>%d</code>, etc.
 Otherwise, a <code>ValueError</code> will be raised.
 
 </p>
 
 </overview>
 <recommendation>
-<p>Choose a legal conversion specifier.</p>
+<p>Ensure a valid conversion specifier is used.</p>
 
 </recommendation>
 <example>
-<p>In <code>format_as_tuple_incorrect</code>, "t" is not a legal conversion specifier.
+<p>In the following example, <code>format_as_tuple_incorrect</code>, <code>%t</code> is not a valid conversion specifier.
 
 </p>
 <sample src="UnsupportedFormatCharacter.py" />
 
 </example>
 <references>
 
-  <li>Python Library Reference: <a href="http://docs.python.org/library/stdtypes.html#string-formatting">String Formatting.</a> </li>
+  <li>Python Library Reference: <a href="https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting">printf-style String Formatting.</a> </li>
 
 </references>
 </qhelp>

python/ql/src/Functions/ConsistentReturns.qhelp

@@ -6,7 +6,7 @@
 
 <overview>
 <p>When a function contains both explicit returns (<code>return value</code>) and implicit returns
-(where code falls off the end of a function) this often indicates that a return
+(where code falls off the end of a function), this often indicates that a return
 statement has been forgotten. It is best to return an explicit return value even when returning
 <code>None</code> because this makes it easier for other developers to read your code.
 </p>
@@ -29,7 +29,7 @@ return value of <code>None</code> as this equates to <code>False</code>. However
 </example>
 <references>
 
-<li>Python Language Reference: <a href="http://docs.python.org/2/reference/compound_stmts.html#function">Function definitions</a>.
+<li>Python Language Reference: <a href="http://docs.python.org/3/reference/compound_stmts.html#function">Function definitions</a>.
 </li>