Python: Fix a bunch of class QLDoc

Author: tausbn

python/ql/lib/semmle/python/AstExtended.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Syntactic node (Class, Function, Module, Expr, Stmt or Comprehension) corresponding to a flow node */
+/** A syntactic node (Class, Function, Module, Expr, Stmt or Comprehension) corresponding to a flow node */
 abstract class AstNode extends AstNode_ {
   /*
    * Special comment for documentation generation.
@@ -61,31 +61,31 @@ abstract class AstNode extends AstNode_ {
 }
 
 /* Parents */
-/** Internal implementation class */
+/** The parent of a `Function`. Internal implementation class */
 class FunctionParent extends FunctionParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `Arguments` node. Internal implementation class */
 class ArgumentsParent extends ArgumentsParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `ExprList`. Internal implementation class */
 class ExprListParent extends ExprListParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `ExprContext`. Internal implementation class */
 class ExprContextParent extends ExprContextParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `StmtList`. Internal implementation class */
 class StmtListParent extends StmtListParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `StrList`. Internal implementation class */
 class StrListParent extends StrListParent_ { }
 
-/** Internal implementation class */
+/** The parent of an `Expr`. Internal implementation class */
 class ExprParent extends ExprParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `PatternList`. Internal implementation class */
 class PatternListParent extends PatternListParent_ { }
 
-/** Internal implementation class */
+/** The parent of a `Pattern`. Internal implementation class */
 class PatternParent extends PatternParent_ { }
 
 class DictItem extends DictItem_, AstNode {
@@ -120,7 +120,7 @@ class Comprehension extends Comprehension_, AstNode {
 class BytesOrStr extends BytesOrStr_ { }
 
 /**
- * Part of a string literal formed by implicit concatenation.
+ * A part of a string literal formed by implicit concatenation.
  * For example the string literal "abc" expressed in the source as `"a" "b" "c"`
  * would be composed of three `StringPart`s.
  */

python/ql/lib/semmle/python/Comprehensions.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Base class for list, set and dictionary comprehensions, and generator expressions. */
+/** The base class for list, set and dictionary comprehensions, and generator expressions. */
 abstract class Comp extends Expr {
   abstract Function getFunction();
 

python/ql/lib/semmle/python/Exprs.qll

@@ -315,7 +315,7 @@ class Ellipsis extends Ellipsis_ {
 }
 
 /**
- * Immutable literal expressions (except tuples).
+ * An immutable literal expression (except tuples).
  * Consists of string (both unicode and byte) literals and numeric literals.
  */
 abstract class ImmutableLiteral extends Expr {
@@ -687,7 +687,7 @@ class False extends BooleanLiteral {
   override boolean booleanValue() { result = false }
 }
 
-/** `None` */
+/** The `None` constant. */
 class None extends NameConstant {
   /* syntax: None */
   None() { name_consts(this, "None") }
@@ -730,20 +730,20 @@ class Guard extends Guard_ {
 /** A context in which an expression used */
 class ExprContext extends ExprContext_ { }
 
-/** Load context, the context of var in len(var) */
+/** The load context, the context of var in len(var) */
 class Load extends Load_ { }
 
-/** Store context, the context of var in var = 0 */
+/** The store context, the context of var in var = 0 */
 class Store extends Store_ { }
 
-/** Delete context, the context of var in del var */
+/** The delete context, the context of var in del var */
 class Del extends Del_ { }
 
-/** This is an artifact of the Python grammar which includes an AugLoad context, even though it is never used. */
+/** The context of an augmented load. This is an artifact of the Python grammar which includes an AugLoad context, even though it is never used. */
 class AugLoad extends AugLoad_ { }
 
-/** Augmented store context, the context of var in var += 1 */
+/** The augmented store context, the context of var in var += 1 */
 class AugStore extends AugStore_ { }
 
-/** Parameter context, the context of var in def f(var): pass */
+/** The parameter context, the context of var in def f(var): pass */
 class Param extends Param_ { }

python/ql/lib/semmle/python/Operations.qll

@@ -1,6 +1,6 @@
 import python
 
-/** Base class for operators */
+/** The base class for operators */
 class Operator extends Operator_ {
   /** Gets the name of the special method used to implement this operator */
   string getSpecialMethodName() { none() }
@@ -131,7 +131,7 @@ class Compare extends Compare_ {
   }
 }
 
-/** List of comparison operators in a comparison */
+/** A list of comparison operators in a comparison */
 class CmpopList extends CmpopList_ { }
 
 /** A comparison operator */

python/ql/lib/semmle/python/SelfAttribute.qll

@@ -31,7 +31,7 @@ private predicate self_attribute(Attribute attr, Class cls) {
   )
 }
 
-/** Helper class for UndefinedClassAttribute.ql & MaybeUndefinedClassAttribute.ql */
+/** A helper class for UndefinedClassAttribute.ql & MaybeUndefinedClassAttribute.ql */
 class SelfAttributeRead extends SelfAttribute {
   SelfAttributeRead() {
     this.getCtx() instanceof Load and

python/ql/lib/semmle/python/dataflow/new/SensitiveDataSources.qll

@@ -227,7 +227,7 @@ private module SensitiveDataModeling {
   }
 
   /**
-   * Any kind of variable assignment (also including with/for) where the name indicates
+   * A variable assignment (also including with/for) where the name indicates
    * it contains sensitive data.
    *
    * Note: We _could_ make any access to a variable with a sensitive name a source of

python/ql/lib/semmle/python/dataflow/new/TypeTracker.qll

@@ -6,14 +6,14 @@
 private import python
 private import internal.TypeTracker as Internal
 
-/** Any string that may appear as the name of an attribute or access path. */
+/** A string that may appear as the name of an attribute or access path. */
 class AttributeName = Internal::ContentName;
 
-/** Either an attribute name, or the empty string (representing no attribute). */
+/** An attribute name, or the empty string (representing no attribute). */
 class OptionalAttributeName = Internal::OptionalContentName;
 
 /**
- * Summary of the steps needed to track a value to a given dataflow node.
+ * The summary of the steps needed to track a value to a given dataflow node.
  *
  * This can be used to track objects that implement a certain API in order to
  * recognize calls to that API. Note that type-tracking does not by itself provide a

python/ql/lib/semmle/python/dataflow/new/internal/DataFlowPrivate.qll

@@ -613,7 +613,7 @@ newtype TDataFlowCallable =
   TLambda(Function lambda) { lambda.isLambda() } or
   TModule(Module m)
 
-/** Represents a callable. */
+/** A callable. */
 abstract class DataFlowCallable extends TDataFlowCallable {
   /** Gets a textual representation of this element. */
   abstract string toString();
@@ -714,7 +714,7 @@ newtype TDataFlowCall =
   TClassCall(CallNode call) { call = any(ClassValue c | not c.isAbsent()).getACall() } or
   TSpecialCall(SpecialMethodCallNode special)
 
-/** Represents a call. */
+/** A call. */
 abstract class DataFlowCall extends TDataFlowCall {
   /** Gets a textual representation of this element. */
   abstract string toString();
@@ -739,7 +739,7 @@ abstract class DataFlowCall extends TDataFlowCall {
 }
 
 /**
- * Represents a call to a function/lambda.
+ * A call to a function/lambda.
  * This excludes calls to bound methods, classes, and special methods.
  * Bound method calls and class calls insert an argument for the explicit
  * `self` parameter, and special method calls have special argument passing.
@@ -826,7 +826,7 @@ class ClassCall extends DataFlowCall, TClassCall {
   override DataFlowCallable getEnclosingCallable() { result.getScope() = call.getScope() }
 }
 
-/** Represents a call to a special method. */
+/** A call to a special method. */
 class SpecialCall extends DataFlowCall, TSpecialCall {
   SpecialMethodCallNode special;
 

python/ql/lib/semmle/python/dataflow/old/Implementation.qll

@@ -79,7 +79,7 @@ abstract class AttributePath extends TAttributePath {
   predicate noAttribute() { this = TNoAttribute() }
 }
 
-/** AttributePath for no attribute. */
+/** The `AttributePath` for no attribute. */
 class NoAttribute extends TNoAttribute, AttributePath {
   override string toString() { result = "no attribute" }
 
@@ -88,7 +88,7 @@ class NoAttribute extends TNoAttribute, AttributePath {
   override AttributePath fromAttribute(string name) { none() }
 }
 
-/** AttributePath for an attribute. */
+/** The `AttributePath` for an attribute. */
 class NamedAttributePath extends TAttribute, AttributePath {
   override string toString() {
     exists(string attr |
@@ -124,8 +124,8 @@ newtype TTaintTrackingNode =
   }
 
 /**
- * Class representing the (node, context, path, kind) tuple.
- *  Used for context-sensitive path-aware taint-tracking.
+ * A class representing the (node, context, path, kind) tuple.
+ * Used for context-sensitive path-aware taint-tracking.
  */
 class TaintTrackingNode extends TTaintTrackingNode {
   /** Gets a textual representation of this element. */

python/ql/lib/semmle/python/dataflow/old/TaintTracking.qll

@@ -180,7 +180,7 @@ abstract class TaintKind extends string {
 }
 
 /**
- * Alias of `TaintKind`, so the two types can be used interchangeably.
+ * An Alias of `TaintKind`, so the two types can be used interchangeably.
  */
 class FlowLabel = TaintKind;
 
@@ -561,7 +561,7 @@ module DataFlowExtension {
     ControlFlowNode getACalleeSuccessorNode(CallNode call) { none() }
   }
 
-  /** Data flow variable that modifies the basic data-flow. */
+  /** A data flow variable that modifies the basic data-flow. */
   class DataFlowVariable extends EssaVariable {
     /**
      * Gets a successor node for data-flow.
@@ -608,7 +608,7 @@ private import semmle.python.pointsto.PointsTo
  */
 module DataFlow {
   /**
-   * Generic taint kind, source and sink classes for convenience and
+   * The generic taint kind, source and sink classes for convenience and
    * compatibility with other language libraries
    */
   class Extension = DataFlowExtension::DataFlowNode;