Edit query metadata and help and add new entry to the change-notes 1.21

Author: alexey

change-notes/1.21/analysis-python.md

@@ -10,7 +10,7 @@
   | **Query** | **Tags** | **Purpose** |
   |-----------|----------|-------------|
   | Accepting unknown SSH host keys when using Paramiko (`py/paramiko-missing-host-key-validation`) | security, external/cwe/cwe-295 | Finds instances where Paramiko is configured to accept unknown host keys. Results are shown on LGTM by default. |
-
+  | Using `return`, `yield`, or `yield from` outside a function or a class method | reliability, correctness | Finds instances where `return`, `yield`, and `yield from` are used outside a function. Results are not shown on LGTM by default. |
 
 ## Changes to existing queries
 

python/ql/src/Statements/ReturnOrYieldOutsideOfFunction.qhelp

@@ -4,20 +4,20 @@
 <qhelp>
 
 <overview>
-<p>In Python, <code>return</code> and <code>yield</code> statements as well as <code>yield from</code>
-expression can only be used within a function. Having them placed outside of a function or a class
-method will raise a <code>SyntaxError</code> at runtime.</p>
+<p>In Python, <code>return</code> and <code>yield</code> statements and the <code>yield from</code>
+expression can only be used within a function. Using them outside a function or a class
+method results in a <code>SyntaxError</code> at runtime.</p>
 </overview>
 
 <recommendation>
-<p>The presence of <code>return</code> and <code>yield</code> statements or <code>yield from</code>
-expression outside of a function or a class method suggests a logical error, so it is not possible
-to suggest a general fix.</p>
+<p>Using these elements outside a function or a class method usually indicates an error in the logic.
+Consequently, it is not possible to suggest a general fix.</p>
 </recommendation>
 
 <example>
-<p>In this example, a <code>return</code> statement is used outside of a class method in a class and
-a <code>yield</code> statement is used outside of a function in a scope of a module.</p>
+<p>In this example, a <code>return</code> statement is used outside a class method in a class and
+a <code>yield</code> statement is used outside a function in a scope of a module which would result
+in a <code>SyntaxError</code> when running this code.</p>
 <sample src="ReturnOrYieldOutsideOfFunction.py" />
 </example>
 

python/ql/src/Statements/ReturnOrYieldOutsideOfFunction.ql

@@ -1,6 +1,6 @@
 /**
- * @name return or yield are used outside of a function
- * @description return and yield statements should be used only within a function.
+ * @name Using 'return' or 'yield' outside a function causes a 'SyntaxError' at runtime
+ * @description Statements 'return' and 'yield' should be used only within a function.
  * @kind problem
  * @tags reliability
  *       correctness