Update rules metadata (#1504)

Author: guillaume-dequenne

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/PreIncrementDecrement.html

@@ -1,12 +1,18 @@
+<p>This rule raises an issue when a pre/post increment or decrement operator is used.</p>
 <h2>Why is this an issue?</h2>
 <p>Python has no pre/post increment/decrement operator. For instance, <code>x++</code> and <code>x--</code> will fail to parse. More importantly,
 <code>++x</code> and <code>--x</code> will do nothing. To increment a number, simply write <code>x += 1</code>.</p>
-<h3>Noncompliant code example</h3>
-<pre>
-++x # Noncompliant
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+++x # Noncompliant: pre and post increment operators do not exist in Python.
+
+x-- # Noncompliant: pre and post decrement operators do not exist in Python.
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
 x += 1
+
+x -= 1
 </pre>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S1045.html

@@ -1,43 +1,54 @@
+<p>This rule raises an issue when an <code>except</code> statement has had all its exceptions caught by a previous <code>except</code> clause.</p>
 <h2>Why is this an issue?</h2>
-<p>Exceptions handlers (<code>except:</code>) are evaluated in the order they are written. Once a match is found, the evaluation stops.</p>
-<p>In some contexts an except block is dead code as it will never catch any exception:</p>
+<p>Exceptions handlers (<code>except</code>) are evaluated in the order they are written. Once a match is found, the evaluation stops.</p>
+<p>In some contexts, an except block is dead code as it will never catch any exception:</p>
 <ul>
   <li> If there is a handler for a base class followed by a handler for class derived from that base class, the second handler will never trigger: The
   handler for the base class will match the derived class, and will be the only executed handler. </li>
   <li> When multiple <code>except</code> statements try to catch the same exception class, only the first one will be executed. </li>
-  <li> In python 3, <code>BaseException</code> is the parent of every exception class. When <code>BaseException</code> is caught and the same
-  try-except block has a bare <code>except:</code> statement, i.e. an <code>except</code> with no expression, the bare except will never catch
-  anything. </li>
+  <li> In Python 3, <code>BaseException</code> is the parent of every exception class. When a <code>BaseException</code> is caught by an
+  <code>except</code> clause, none of the subsequent <code>except</code> statement will catch anything. This is true as well for the bare except
+  statement (<code>except:</code>). </li>
 </ul>
-<p>This rule raises an issue when an <code>except</code> block catches every exception before a later <code>except</code> block could catch it.</p>
-<h3>Noncompliant code example</h3>
-<pre>
+<h2>How to fix it</h2>
+<p>When using multiple <code>except</code> statements, make sure to:</p>
+<ul>
+  <li> Order the <code>except</code> blocks from the most specialzed exception to the most generic, i.e when wanting to catch a
+  <code>FloatingPointError</code> and an <code>ArithemticError</code>, as <code>FloatingPointError</code> is a subclass of
+  <code>ArithmeticError</code>, the first <code>except</code> statement should be <code>FloatingPointError</code>. </li>
+  <li> Catch the same exception only once. </li>
+  <li> Catch a <code>BaseException</code> only once with either an <code>except BaseException:</code> statement or a bare <code>except:</code>
+  statement, as the two statements are equivalent. </li>
+</ul>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
 def foo():
     try:
         raise FloatingPointError()
     except (ArithmeticError, RuntimeError) as e:
         print(e)
-    except FloatingPointError as e: # Noncompliant. FloatingPointError is a subclass of ArithmeticError
+    except FloatingPointError as e: # Noncompliant: FloatingPointError is a subclass of ArithmeticError.
         print("Never executed")
-    except OverflowError as e: # Noncompliant. OverflowError is a subclass of ArithmeticError
+    except OverflowError as e: # Noncompliant: OverflowError is a subclass of ArithmeticError.
         print("Never executed")
 
     try:
         raise TypeError()
     except TypeError as e:
         print(e)
-    except TypeError as e: # Noncompliant. Duplicate Except.
+    except TypeError as e: # Noncompliant: duplicate except.
         print("Never executed")
 
     try:
         raise ValueError()
     except BaseException as e:
         print(e)
-    except: # Noncompliant. This is equivalent to "except BaseException" block
+    except: # Noncompliant: this is equivalent to "except BaseException" block.
         print("Never executed")
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
 def foo():
     try:
         raise FloatingPointError()
@@ -58,9 +69,13 @@ <h3>Compliant solution</h3>
     except BaseException as e:
         print(e)
 </pre>
+<p><strong>Note</strong>: <em>It is generally not recommended to try catching <code>BaseException</code>, as it is the base class for all built-in
+exceptions in Python, including system-exiting exceptions like <code>SystemExit</code> or <code>KeyboardInterrupt</code>, which are typically not
+meant to be caught. See <a href="https://www.python.org/dev/peps/pep-0352/#exception-hierarchy-changes">PEP 352</a> for more information.</em></p>
 <h2>Resources</h2>
+<h3>Documentation</h3>
 <ul>
-  <li> Python Documentation - <a href="https://docs.python.org/3/reference/compound_stmts.html#the-try-statement">The <code>try</code> statement</a>
-  </li>
+  <li> <a href="https://docs.python.org/3/reference/compound_stmts.html#the-try-statement">The <code>try</code> statement</a> </li>
+  <li> <a href="https://docs.python.org/3/library/exceptions.html#exception-hierarchy">Exception hierarchy</a> </li>
 </ul>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S108.html

@@ -6,7 +6,7 @@ <h2>Why is this an issue?</h2>
 for i in range(3):
     pass
 </pre>
-<p>Removing or filling the empty code blocks takes away ambiguity and generally results in a more straightforward and less surprising code. ===
-Exceptions</p>
+<p>Removing or filling the empty code blocks takes away ambiguity and generally results in a more straightforward and less surprising code.</p>
+<h3>Exceptions</h3>
 <p>The rule ignores code blocks that contain comments.</p>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S1716.html

@@ -1,18 +1,48 @@
+<p>This rule raises an issue when a <code>break</code> or <code>continue</code> statement is used outside of a loop.</p>
 <h2>Why is this an issue?</h2>
-<p><code>break</code> and <code>continue</code> are unstructured control flow statements which make code harder to read. Additionally, more recent
-versions of Python raise a SyntaxError when modules containing <code>break</code> or <code>continue</code> outside of a loop are imported.</p>
-<p>Therefore, these statements should not be used outside of loops.</p>
-<h3>Noncompliant code example</h3>
+<p><code>break</code> and <code>continue</code> are control flow statements used inside of loops. <code>break</code> is used to break out of its
+innermost enclosing loop and <code>continue</code> will continue with the next iteration.</p>
+<p>The example below illustrates the use of <code>break</code> in a <code>while</code> loop:</p>
 <pre>
+n = 1
+while n &lt; 10:
+    if n % 3 == 0:
+      print("Found a number divisible by 3", n)
+      break
+    n = n + 1
+</pre>
+<p>This next example uses <code>continue</code> inside a <code>for</code> loop:</p>
+<pre>
+words = ["alice", "bob", "charlie"]
+for word in words:
+    if word == word[::-1]:
+        print("Found a palindrome", word)
+        continue
+    print("This is not a palindrome", word)
+</pre>
+<p>Python will raise a <code>SyntaxError</code> when <code>break</code> or <code>continue</code> are used outside of <code>for</code> or
+<code>while</code> loops.</p>
+<p>If the goal is to interrupt the main program flow, <code>quit()</code>, <code>exit()</code>, <code>os._exit()</code> and <code>sys.exit()</code>
+are the preferred way.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
 narg=len(sys.argv)
 if narg == 1:
-        print('@Usage: input_filename nelements nintervals')
-        break
+    print('@Usage: input_filename nelements nintervals')
+    break
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+narg=len(sys.argv)
 if narg == 1:
-        print('@Usage: input_filename nelements nintervals')
-        sys.exit()
+    print('@Usage: input_filename nelements nintervals')
+    sys.exit()
 </pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> <a href="https://docs.python.org/3/tutorial/controlflow.html#break-and-continue-statements-and-else-clauses-on-loops">break and continue
+  Statements</a> </li>
+</ul>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S2711.html

@@ -1,10 +1,38 @@
+<p>This rule raises an issue when <code>return</code> or <code>yield</code> are used outside of a function.</p>
 <h2>Why is this an issue?</h2>
 <p><code>yield</code> and <code>return</code> only make sense in the context of functions. Using them outside a function raises a
-<code>SyntaxError</code>. To break out of a loop, use <code>break</code> instead.</p>
-<h3>Noncompliant code example</h3>
-<pre>
-class MyClass:
-    while True:
-        return False #Noncompliant
+<code>SyntaxError</code>.</p>
+<p>If the goal is to break out of a loop, use <code>break</code> instead of <code>return</code>.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+a = 1
+while a &lt; 3:
+    if a % 2 == 0:
+        return # Noncompliant: return is outside of a function
+    a += 1
+
+for n in range(5):
+  yield n # Noncompliant: yield is outside of a function
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+a = 1
+while a &lt; 3:
+    if a % 2 == 0:
+        break
+    a += 1
+
+def gen():
+    for n in range(5):
+      yield n
 </pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> Python Documentation - <a href="https://docs.python.org/3/reference/expressions.html?highlight=yield#yield-expressions">Yield expressions</a>
+  </li>
+  <li> Python Documentation - <a href="https://docs.python.org/3/reference/simple_stmts.html?highlight=return%20tatement#the-return-statement">Return
+  statement</a> </li>
+</ul>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S2734.html

@@ -1,20 +1,28 @@
+<p>This rule raises an issue when the <code>__init__</code> method of a class contains a <code>return</code> or a <code>yield</code> statement.</p>
 <h2>Why is this an issue?</h2>
-<p>By contract, every Python function returns something, even if it’s the <code>None</code> value, which can be returned implicitly by omitting the
+<p>By contract, every Python function returns something, even if it is the <code>None</code> value, which can be returned implicitly by omitting the
 <code>return</code> statement, or explicitly.</p>
 <p>The <code>__init__</code> method is required to return <code>None</code>. A <code>TypeError</code> will be raised if the <code>__init__</code>
-method either <code>yield</code>s or <code>return</code>s any expression other than <code>None</code>. Returning some expression that evaluates to
-<code>None</code> will not raise an error, but is considered bad practice.</p>
-<h3>Noncompliant code example</h3>
-<pre>
+method either yields or returns any expression other than <code>None</code>. While explicitly returning an expression that evaluates to
+<code>None</code> will not raise an error, it is considered bad practice.</p>
+<p>To fix this issue, make sure that the <code>__init__</code> method does not contain any return statement.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
 class MyClass(object):
     def __init__(self):
         self.message = 'Hello'
-        return self  # Noncompliant
+        return self  # Noncompliant: a TypeError will be raised
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
 class MyClass(object):
     def __init__(self):
         self.message = 'Hello'
 </pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> <a href="https://docs.python.org/3/reference/datamodel.html#object.__init__">The <code>__init__</code> method</a> </li>
+</ul>
 

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S2737.html

@@ -1,16 +1,14 @@
 <h2>Why is this an issue?</h2>
 <p>An <code>except</code> clause that only rethrows the caught exception has the same effect as omitting the <code>except</code> altogether and
-letting it bubble up automatically, but with more code and the additional detriment of leaving maintainers scratching their heads.</p>
-<p>Such clauses should either be eliminated or populated with the appropriate logic.</p>
-<h3>Noncompliant code example</h3>
+letting it bubble up automatically.</p>
 <pre>
 a = {}
 try:
     a[5]
 except KeyError:
     raise  # Noncompliant
 </pre>
-<h3>Compliant solution</h3>
+<p>Such clauses should either be removed or populated with the appropriate logic.</p>
 <pre>
 a = {}
 try: