Update docs

Author: joefarebrother

python/ql/src/Functions/NonCls.py

@@ -1,4 +1,4 @@
 class Entry(object):
     @classmethod
-    def make(klass):
+    def make(self):
         return Entry()

python/ql/src/Functions/NonCls.qhelp

@@ -5,20 +5,19 @@
 
 
 <overview>
-<p> The first parameter of a class method, a new method or any metaclass method
-should be called <code>cls</code>. This makes the purpose of the parameter clear to other developers.
+<p> The first parameter of a class method (including certain special methods such as <code>__new__</code>), or a method of a metaclass,
+should be named <code>cls</code>. 
 </p>
 
 </overview>
 <recommendation>
 
-<p>Change the name of the first parameter to <code>cls</code> as recommended by the style guidelines
+<p>Ensure that the first parameter of class methods is named <code>cls</code>, as recommended by the style guidelines
 in PEP 8.</p>
 
 </recommendation>
 <example>
-<p>In the example, the first parameter to <code>make()</code> is <code>klass</code> which should be changed to <code>cls</code>
-for ease of comprehension.
+<p>In the following example, the first parameter of the class method <code>make</code> is named <code>self</code> instead of <code>cls</code>.
 </p>
 
 <sample src="NonCls.py" />
@@ -29,6 +28,7 @@ for ease of comprehension.
 
 <li>Python PEP 8: <a href="http://www.python.org/dev/peps/pep-0008/#function-and-method-arguments">Function and method arguments</a>.</li>
 <li>Python Tutorial: <a href="http://docs.python.org/2/tutorial/classes.html">Classes</a>.</li>
+<li>Python Docs: <a href="https://docs.python.org/3/library/functions.html#classmethod"><code>classmethod</code></a>.</li>
 
 
 </references>

python/ql/src/Functions/NonCls.ql

@@ -1,7 +1,6 @@
 /**
  * @name First parameter of a class method is not named 'cls'
- * @description Using an alternative name for the first parameter of a class method makes code more
- *              difficult to read; PEP8 states that the first parameter to class methods should be 'cls'.
+ * @description By the PEP8 style guide, the first parameter of a class method should be named `cls`.
  * @kind problem
  * @tags maintainability
  *       readability

python/ql/src/Functions/NonSelf.py

@@ -1,9 +1,9 @@
 class Point:
-    def __init__(val, x, y):  # first parameter is mis-named 'val'
+    def __init__(val, x, y):  # BAD: first parameter is mis-named 'val'
         val._x = x
         val._y = y
 
 class Point2:
-    def __init__(self, x, y):  # first parameter is correctly named 'self'
+    def __init__(self, x, y):  # GOOD: first parameter is correctly named 'self'
         self._x = x
         self._y = y

python/ql/src/Functions/NonSelf.qhelp

@@ -6,22 +6,18 @@
 
 <overview>
 <p> Normal methods should have at least one parameter and the first parameter should be called <code>self</code>.
-This makes the purpose of the parameter clear to other developers.
 </p>
 </overview>
 
 <recommendation>
-<p>If there is at least one parameter, then change the name of the first parameter to <code>self</code> as recommended by the style guidelines
+<p>Ensure that the first parameter of a normal method is named <code>self</code>, as recommended by the style guidelines
 in PEP 8.</p>
-<p>If there are no parameters, then it cannot be a normal method. It may need to be marked as a <code>staticmethod</code>
-or it could be moved out of the class as a normal function.
+<p>If a <code>self</code> parameter is unneeded, the method should be decorated with <code>staticmethod</code>, or moved out of the class as a regular function.
 </p>
 </recommendation>
 
 <example>
-<p>The following methods can both be used to assign values to variables in a <code>point</code> 
-object. The second method makes the association clearer because the <code>self</code> parameter is 
-used.</p>
+<p>In the following cases, the first argument of <code>Point.__init__</code> is named <code>val</code> instead; whereas in <code>Point2.__init__</code> it is correctly named <code>self</code>.</p>
 <sample src="NonSelf.py" />
 
 
@@ -31,7 +27,7 @@ used.</p>
 <li>Python PEP 8: <a href="http://www.python.org/dev/peps/pep-0008/#function-and-method-arguments">Function and 
 method arguments</a>.</li>
 <li>Python Tutorial: <a href="http://docs.python.org/2/tutorial/classes.html">Classes</a>.</li>
-
+<li>Python Docs: <a href="https://docs.python.org/3/library/functions.html#staticmethod"><code>staticmethod</code></a>.</li>.
 
 
 </references>

python/ql/src/Functions/NonSelf.ql

@@ -1,8 +1,6 @@
 /**
  * @name First parameter of a method is not named 'self'
- * @description Using an alternative name for the first parameter of an instance method makes
- *              code more difficult to read; PEP8 states that the first parameter to instance
- *              methods should be 'self'.
+ * @description By the PEP8 style guide, the first parameter of a normal method should be named `self`.
  * @kind problem
  * @tags maintainability
  *       readability