Update qhelp + alert messages

Author: joefarebrother

python/ql/src/Classes/CallsToInitDel/MissingCallToDel.qhelp

@@ -4,47 +4,49 @@
 <qhelp>
 
 <overview>
-<p>Python, unlike statically typed languages such as Java, allows complete freedom when calling methods during object destruction.
-However, standard object-oriented principles apply to Python classes using deep inheritance hierarchies.
-Therefore the developer has responsibility for ensuring that objects are properly cleaned up when
-there are multiple <code>__del__</code> methods that need to be called.
+<p>
+Python, unlike some other object-oriented languages such as Java, allows the developer complete freedom in 
+when and how superclass finalizers are called during object finalization.
+However, the developer has responsibility for ensuring that objects are properly cleaned up, and that all superclass <code>__del__</code> 
+methods are called.
 </p>
 <p>
-If the  <code>__del__</code> method of a superclass is not called during object destruction it is likely that
+Classes with a <code>__del__</code> method (a finalizer) typically hold some resource such as a file handle that needs to be cleaned up. 
+If the  <code>__del__</code> method of a superclass is not called during object finalization, it is likely that
 that resources may be leaked.
 </p>
 
-<p>A call to the <code>__del__</code> method of a superclass during object destruction may be omitted:
+<p>A call to the <code>__init__</code> method of a superclass during object initialization may be unintentionally skipped:
 </p>
 <ul>
-        <li>When a subclass calls the <code>__del__</code> method of the wrong class.</li>
-        <li>When a call to the <code>__del__</code> method of one its base classes is omitted.</li>
+        <li>If a subclass calls the <code>__del__</code> method of the wrong class.</li>
+        <li>If a call to the <code>__del__</code> method of one its base classes is omitted.</li>
+        <li>If a call to <code>super().__del__</code> is used, but not all <code>__del__</code> methods in the Method Resolution Order (MRO)
+        chain themselves call <code>super()</code>. This in particular arises more often in cases of multiple inheritance. </li>
 </ul>
 
 
 </overview>
 <recommendation>
-<p>Either be careful to explicitly call the <code>__del__</code> of the correct base class, or
-use <code>super()</code> throughout the inheritance hierarchy.</p>
-
-<p>Alternatively refactor one or more of the classes to use composition rather than inheritance.</p>
+<p>Ensure that all superclass <code>__del__</code> methods are properly called. 
+Either each base class's finalize method should be explicitly called, or <code>super()</code> calls 
+should be consistently used throughout the inheritance hierarchy.</p>
 
 
 </recommendation>
 <example>
-<p>In this example, explicit calls to <code>__del__</code> are used, but <code>SportsCar</code> erroneously calls
+<p>In the following example, explicit calls to <code>__del__</code> are used, but <code>SportsCar</code> erroneously calls
 <code>Vehicle.__del__</code>. This is fixed in <code>FixedSportsCar</code> by calling <code>Car.__del__</code>.
 </p>
 
-<sample src="MissingCallToDel.py" />
+<sample src="examples/MissingCallToDel.py" />
 
 </example>
 <references>
 
-        <li>Python Tutorial: <a href="https://docs.python.org/2/tutorial/classes.html">Classes</a>.</li>
-        <li>Python Standard Library: <a href="https://docs.python.org/2/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>
-        <li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Composition_over_inheritance">Composition over inheritance</a>.</li>
+        <li>Python Reference: <a href="https://docs.python.org/3/reference/datamodel.html#object.__del__">__del__</a>.</li>
+        <li>Python Standard Library: <a href="https://docs.python.org/3/library/functions.html#super">super</a>.</li>
+        <li>Python Glossary: <a href="https://docs.python.org/3/glossary.html#term-method-resolution-order">Method resolution order</a>.</li>
 
 </references>
 </qhelp>

python/ql/src/Classes/CallsToInitDel/MissingCallToDel.ql

@@ -30,18 +30,18 @@ where
       not possiblyMissingSuper.isNone() and
       possibleIssue = possiblyMissingSuper and
       msg =
-        "This class does not call $@ during destruction. ($@ may be missing a call to super().__del__)"
+        "This class does not call $@ during finalization. ($@ may be missing a call to super().__del__)"
       or
       possiblyMissingSuper.isNone() and
       (
         possibleIssue.asSome() = getDelMethod(base) and
         msg =
-          "This class does not call $@ during destruction. ($@ may be missing a call to a base class __del__)"
+          "This class does not call $@ during finalization. ($@ may be missing a call to a base class __del__)"
         or
         not exists(getDelMethod(base)) and
         possibleIssue.isNone() and
         msg =
-          "This class does not call $@ during destruction. (The class lacks an __del__ method to ensure every base class __del__ is called.)"
+          "This class does not call $@ during finalization. (The class lacks an __del__ method to ensure every base class __del__ is called.)"
       )
     )
   )

python/ql/src/Classes/CallsToInitDel/MissingCallToInit.qhelp

@@ -4,49 +4,47 @@
 <qhelp>
 
 <overview>
-<p>Python, unlike statically typed languages such as Java, allows complete freedom when calling methods during object initialization.
-However, standard object-oriented principles apply to Python classes using deep inheritance hierarchies.
-Therefore the developer has responsibility for ensuring that objects are properly initialized when
-there are multiple <code>__init__</code> methods that need to be called.
+<p>Python, unlike some other object-oriented languages such as Java, allows the developer complete freedom in 
+when and how superclass initializers are called during object initialization.
+However, the developer has responsibility for ensuring that objects are properly initialized, and that all superclass <code>__init__</code> 
+methods are called.
 </p>
 <p>
-If the  <code>__init__</code> method of a superclass is not called during object initialization it is likely that
-that object will end up in an incorrect state.
+If the  <code>__init__</code> method of a superclass is not called during object initialization, this can lead to errors due to
+the object not being fully initialized, such as having missing attributes.
 </p>
 
-<p>A call to the <code>__init__</code> method of a superclass during object initialization may be omitted:
+<p>A call to the <code>__init__</code> method of a superclass during object initialization may be unintentionally skipped:
 </p>
 <ul>
-        <li>When a subclass calls the <code>__init__</code> method of the wrong class.</li>
-        <li>When a call to the <code>__init__</code> method of one its base classes is omitted.</li>
-        <li>When multiple inheritance is used and a class inherits from several base classes,
-        and at least one of those does not use <code>super()</code> in its own <code>__init__</code> method.</li>
+        <li>If a subclass calls the <code>__init__</code> method of the wrong class.</li>
+        <li>If a call to the <code>__init__</code> method of one its base classes is omitted.</li>
+        <li>If a call to <code>super().__init__</code> is used, but not all <code>__init__</code> methods in the Method Resolution Order (MRO)
+        chain themselves call <code>super()</code>. This in particular arises more often in cases of multiple inheritance. </li>
 </ul>
 
 
 </overview>
 <recommendation>
-<p>Either be careful to explicitly call the <code>__init__</code> of the correct base class, or
-use <code>super()</code> throughout the inheritance hierarchy.</p>
-
-<p>Alternatively refactor one or more of the classes to use composition rather than inheritance.</p>
+<p>Ensure that all superclass <code>__init__</code> methods are properly called. 
+Either each base class's initialize method should be explicitly called, or <code>super()</code> calls 
+should be consistently used throughout the inheritance hierarchy.</p>
 
 
 </recommendation>
 <example>
-<p>In this example, explicit calls to <code>__init__</code> are used, but <code>SportsCar</code> erroneously calls
+<p>In the following example, explicit calls to <code>__init__</code> are used, but <code>SportsCar</code> erroneously calls
 <code>Vehicle.__init__</code>. This is fixed in <code>FixedSportsCar</code> by calling <code>Car.__init__</code>.
 </p>
 
-<sample src="MissingCallToInit.py" />
+<sample src="examples/MissingCallToInit.py" />
 
 </example>
 <references>
 
-        <li>Python Tutorial: <a href="https://docs.python.org/2/tutorial/classes.html">Classes</a>.</li>
-        <li>Python Standard Library: <a href="https://docs.python.org/2/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>
-        <li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Composition_over_inheritance">Composition over inheritance</a>.</li>
+        <li>Python Reference: <a href="https://docs.python.org/3/reference/datamodel.html#object.__init__">__init__</a>.</li>
+        <li>Python Standard Library: <a href="https://docs.python.org/3/library/functions.html#super">super</a>.</li>
+        <li>Python Glossary: <a href="https://docs.python.org/3/glossary.html#term-method-resolution-order">Method resolution order</a>.</li>
 
 </references>
 </qhelp>

python/ql/src/Classes/CallsToInitDel/SuperclassDelCalledMultipleTimes.qhelp

@@ -4,55 +4,52 @@
 <qhelp>
 
 <overview>
-<p>Python, unlike statically typed languages such as Java, allows complete freedom when calling methods during object destruction.
-However, standard object-oriented principles apply to Python classes using deep inheritance hierarchies.
-Therefore the developer has responsibility for ensuring that objects are properly cleaned up when
-there are multiple <code>__del__</code> methods that need to be called.
+<p>
+Python, unlike some other object-oriented languages such as Java, allows the developer complete freedom in 
+when and how superclass finalizers are called during object finalization.
+However, the developer has responsibility for ensuring that objects are properly cleaned up.
 </p>
 
 <p>
-Calling a <code>__del__</code> method more than once during object destruction risks resources being released multiple
-times. The relevant <code>__del__</code> method may not be designed to be called more than once.
+Objects with a <code>__del__</code> method (a finalizer) often hold resources such as file handles that need to be cleaned up.
+If a superclass finalizer is called multiple times, this may lead to errors such as closing an already closed file, and lead to objects not being 
+cleaned up properly as expected. 
 </p>
 
 <p>There are a number of ways that a <code>__del__</code> method may be be called more than once.</p>
 <ul>
     <li>There may be more than one explicit call to the method in the hierarchy of <code>__del__</code> methods.</li>
-    <li>A class using multiple inheritance directly calls the <code>__del__</code> methods of its base types.
-    One or more of those base types uses <code>super()</code> to pass down the inheritance chain.</li>
+    <li>In situations involving multiple inheritance, an finalization method may call the finalizers of each of its base types,
+     which themselves both call the finalizer of a shared base type. (This is an example of the Diamond Inheritance problem)</li>
+    <li>Another situation involving multiple inheritance arises when a subclass calls the <code>__del__</code> methods of each of its base classes,
+    one of which calls <code>super().__del__</code>. This super call resolves to the next class in the Method Resolution Order (MRO) of the subclass,
+    which may be another base class that already has its initializer explicitly called.</li>
 </ul>
 
 
 </overview>
 <recommendation>
-<p>Either be careful not to explicitly call a <code>__del__</code> method more than once, or
-use <code>super()</code> throughout the inheritance hierarchy.</p>
-
-<p>Alternatively refactor one or more of the classes to use composition rather than inheritance.</p>
+<p>Ensure that each finalizer method is called exactly once during finalization. 
+This can be ensured by calling <code>super().__del__</code> for each finalizer methid in the inheritance chain.
+</p>
 
 </recommendation>
 <example>
-<p>In the first example, explicit calls to <code>__del__</code> are used, but <code>SportsCar</code> erroneously calls
-both <code>Vehicle.__del__</code> and <code>Car.__del__</code>.
-This can be fixed by removing the call to <code>Vehicle.__del__</code>, as shown in <code>FixedSportsCar</code>.
-</p>
 
-<sample src="SuperclassDelCalledMultipleTimes.py" />
-
-<p>In the second example, there is a mixture of explicit calls to <code>__del__</code> and calls using <code>super()</code>.
-To fix this example, <code>super()</code> should be used throughout.
+<p>In the following example, there is a mixture of explicit calls to <code>__del__</code> and calls using <code>super()</code>, resulting in <code>Vehicle.__del__</code>
+being called twice.
+<code>FixedSportsCar.__del__</code> fixes this by using <code>super()</code> consistently with the other delete methods.
 </p>
 
 <sample src="SuperclassInitCalledMultipleTimes2.py" />
 
 </example>
 <references>
-
-        <li>Python Tutorial: <a href="https://docs.python.org/2/tutorial/classes.html">Classes</a>.</li>
-        <li>Python Standard Library: <a href="https://docs.python.org/2/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>
-        <li>Wikipedia: <a href="http://en.wikipedia.org/wiki/Composition_over_inheritance">Composition over inheritance</a>.</li>
-
+        
+        <li>Python Reference: <a href="https://docs.python.org/3/reference/datamodel.html#object.__del__">__del__</a>.</li>
+        <li>Python Standard Library: <a href="https://docs.python.org/3/library/functions.html#super">super</a>.</li>
+        <li>Python Glossary: <a href="https://docs.python.org/3/glossary.html#term-method-resolution-order">Method resolution order</a>.</li>
+        <li>Wikipedia: <a href="https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem">The Diamond Problem</a>.</li>
 
 </references>
 </qhelp>

python/ql/src/Classes/CallsToInitDel/SuperclassDelCalledMultipleTimes.ql

@@ -36,12 +36,12 @@ where
   (
     target1 != target2 and
     msg =
-      "This deletion method calls $@ multiple times, via $@ and $@, resolving to $@ and $@ respectively."
+      "This finalization method calls $@ multiple times, via $@ and $@, resolving to $@ and $@ respectively."
     or
     target1 = target2 and
     // The targets themselves are called multiple times (either is calledMulti, or something earlier in the MRO)
     // Mentioning them again would be redundant.
-    msg = "This deletion method calls $@ multiple times, via $@ and $@."
+    msg = "This finalization method calls $@ multiple times, via $@ and $@."
   )
 select meth, msg, calledMulti, calledMulti.getQualifiedName(), call1, "this call", call2,
   "this call", target1, target1.getQualifiedName(), target2, target2.getQualifiedName()