PY: fix some ql/non-doc-block warnings

erik-krogh · erik-krogh · commit ddf93b555e69 · 2022-03-11T11:02:58.000+01:00
diff --git a/python/ql/lib/semmle/python/Flow.qll b/python/ql/lib/semmle/python/Flow.qll
@@ -299,7 +299,7 @@ class ControlFlowNode extends @py_flow_node {
     exists(BasicBlock b, int i, int j | this = b.getNode(i) and other = b.getNode(j) and i < j)
   }
 
-  /* Holds if this CFG node is a branch */
+  /** Holds if this CFG node is a branch */
   predicate isBranch() { py_true_successors(this, _) or py_false_successors(this, _) }
 
   ControlFlowNode getAChild() { result = this.getExprChild(this.getBasicBlock()) }
diff --git a/python/ql/lib/semmle/python/dataflow/old/Implementation.qll b/python/ql/lib/semmle/python/dataflow/old/Implementation.qll
@@ -991,7 +991,7 @@ int iterable_unpacking_descent(SequenceNode left_parent, ControlFlowNode left_de
 }
 
 module Implementation {
-  /* A call that returns a copy (or similar) of the argument */
+  /** Holds if `tonode` is a call that returns a copy (or similar) of the argument `fromnode` */
   predicate copyCall(ControlFlowNode fromnode, CallNode tonode) {
     tonode.getFunction().(AttrNode).getObject("copy") = fromnode
     or
diff --git a/python/ql/lib/semmle/python/dataflow/old/Legacy.qll b/python/ql/lib/semmle/python/dataflow/old/Legacy.qll
@@ -2,7 +2,7 @@ import semmle.python.dataflow.TaintTracking
 private import semmle.python.objects.ObjectInternal
 import semmle.python.dataflow.Implementation
 
-/* Backwards compatibility with config-less taint-tracking */
+/** A configuration that provides backwards compatibility with config-less taint-tracking */
 private class LegacyConfiguration extends TaintTracking::Configuration {
   LegacyConfiguration() {
     /* A name that won't be accidentally chosen by users */
diff --git a/python/ql/lib/semmle/python/dependencies/Dependencies.qll b/python/ql/lib/semmle/python/dependencies/Dependencies.qll
@@ -158,13 +158,13 @@ private predicate defn_of_instance_attribute(Assign asgn, Class c, string name)
   )
 }
 
-/* Whether asgn defines an attribute of a class */
+/** Holds if asgn defines an attribute of a class */
 private predicate defn_of_class_attribute(Assign asgn, Class c, string name) {
   asgn.getScope() = c and
   asgn.getATarget().(Name).getId() = name
 }
 
-/* Holds if `value` is a value assigned to the `name`d attribute of module `m`. */
+/** Holds if `value` is a value assigned to the `name`d attribute of module `m`. */
 private predicate defn_of_module_attribute(ControlFlowNode value, Module m, string name) {
   exists(DefinitionNode def |
     def.getScope() = m and
diff --git a/python/ql/lib/semmle/python/objects/ObjectAPI.qll b/python/ql/lib/semmle/python/objects/ObjectAPI.qll
@@ -18,7 +18,7 @@ private import semmle.python.types.Builtins
 
 class ObjectSource = Object;
 
-/* Aliases for scopes */
+/** An alias for Function used for scopes */
 class FunctionScope = Function;
 
 class ClassScope = Class;
diff --git a/python/ql/lib/semmle/python/pointsto/Base.qll b/python/ql/lib/semmle/python/pointsto/Base.qll
@@ -120,7 +120,7 @@ int version_tuple_compare(Object t) {
   version_tuple_value(t) > major_minor() and result = 1
 }
 
-/* Holds if `cls` is a new-style class if it were to have no explicit base classes */
+/** Holds if `cls` is a new-style class if it were to have no explicit base classes */
 predicate baseless_is_new_style(ClassObject cls) {
   cls.isBuiltin()
   or
diff --git a/python/ql/lib/semmle/python/pointsto/PointsTo.qll b/python/ql/lib/semmle/python/pointsto/PointsTo.qll
@@ -2395,7 +2395,7 @@ module Types {
     )
   }
 
-  /* Holds if type inference failed to compute the full class hierarchy for this class for the reason given. */
+  /** Holds if type inference failed to compute the full class hierarchy for this class for the reason given. */
   private predicate failedInference(ClassObjectInternal cls, string reason, int priority) {
     strictcount(cls.(PythonClassObjectInternal).getScope().getADecorator()) > 1 and
     reason = "Multiple decorators" and
diff --git a/python/ql/lib/semmle/python/security/strings/Common.qll b/python/ql/lib/semmle/python/security/strings/Common.qll
@@ -1,6 +1,6 @@
 import python
 
-/* A call that returns a copy (or similar) of the argument */
+/** A call that returns a copy (or similar) of the argument */
 deprecated predicate copy_call(ControlFlowNode fromnode, CallNode tonode) {
   tonode.getFunction().(AttrNode).getObject("copy") = fromnode
   or
diff --git a/python/ql/lib/semmle/python/types/ClassObject.qll b/python/ql/lib/semmle/python/types/ClassObject.qll
@@ -166,7 +166,7 @@ class ClassObject extends Object {
     not this.failedInference()
   }
 
-  /* Whether this class is abstract. */
+  /** Holds if this class is abstract. */
   predicate isAbstract() {
     this.getMetaClass() = theAbcMetaClassObject()
     or
diff --git a/python/ql/src/Lexical/CommentedOutCode.qll b/python/ql/src/Lexical/CommentedOutCode.qll
@@ -158,11 +158,11 @@ private predicate commented_out_code_block(Comment start, Comment end) {
   not commented_out_code(non_empty_following(end))
 }
 
-/* A single line comment that appears to be commented out code */
+/** A single line comment that appears to be commented out code */
 class CommentedOutCodeLine extends Comment {
   CommentedOutCodeLine() { exists(CommentedOutCodeBlock b | b.contains(this)) }
 
-  /* Whether this commented-out code line is likely to be example code embedded in a larger comment. */
+  /** Holds if this commented-out code line is likely to be example code embedded in a larger comment. */
   predicate maybeExampleCode() {
     exists(CommentedOutCodeBlock block |
       block.contains(this) and
diff --git a/python/ql/src/Resources/FileOpen.qll b/python/ql/src/Resources/FileOpen.qll
@@ -66,7 +66,7 @@ predicate passes_open_files(Variable v, ControlFlowNode test, boolean sense) {
   )
 }
 
-/* Helper for `def_is_open` to give better join order */
+// Helper for `def_is_open` to give better join order
 private predicate passes_open_files(PyEdgeRefinement refinement) {
   passes_open_files(refinement.getSourceVariable(), refinement.getPredecessor().getLastNode(),
     refinement.getSense())

Original file line number	Diff line number	Diff line change
`@@ -299,7 +299,7 @@ class ControlFlowNode extends @py_flow_node {`
`299`	`299`	`exists(BasicBlock b, int i, int j \| this = b.getNode(i) and other = b.getNode(j) and i < j)`
`300`	`300`	`}`
`301`	`301`
`302`		`- /* Holds if this CFG node is a branch */`
	`302`	`+ /** Holds if this CFG node is a branch */`
`303`	`303`	`predicate isBranch() { py_true_successors(this, _) or py_false_successors(this, _) }`
`304`	`304`
`305`	`305`	`ControlFlowNode getAChild() { result = this.getExprChild(this.getBasicBlock()) }`
Original file line number	Diff line number	Diff line change
`@@ -991,7 +991,7 @@ int iterable_unpacking_descent(SequenceNode left_parent, ControlFlowNode left_de`
`991`	`991`	`}`
`992`	`992`
`993`	`993`	`module Implementation {`
`994`		`- /* A call that returns a copy (or similar) of the argument */`
	`994`	+ /** Holds if `tonode` is a call that returns a copy (or similar) of the argument `fromnode` */
`995`	`995`	`predicate copyCall(ControlFlowNode fromnode, CallNode tonode) {`
`996`	`996`	`tonode.getFunction().(AttrNode).getObject("copy") = fromnode`
`997`	`997`	`or`
Original file line number	Diff line number	Diff line change
`@@ -158,13 +158,13 @@ private predicate defn_of_instance_attribute(Assign asgn, Class c, string name)`
`158`	`158`	`)`
`159`	`159`	`}`
`160`	`160`
`161`		`-/* Whether asgn defines an attribute of a class */`
	`161`	`+/** Holds if asgn defines an attribute of a class */`
`162`	`162`	`private predicate defn_of_class_attribute(Assign asgn, Class c, string name) {`
`163`	`163`	`asgn.getScope() = c and`
`164`	`164`	`asgn.getATarget().(Name).getId() = name`
`165`	`165`	`}`
`166`	`166`
`167`		-/* Holds if `value` is a value assigned to the `name`d attribute of module `m`. */
	`167`	+/** Holds if `value` is a value assigned to the `name`d attribute of module `m`. */
`168`	`168`	`private predicate defn_of_module_attribute(ControlFlowNode value, Module m, string name) {`
`169`	`169`	`exists(DefinitionNode def \|`
`170`	`170`	`def.getScope() = m and`
Original file line number	Diff line number	Diff line change
`@@ -120,7 +120,7 @@ int version_tuple_compare(Object t) {`
`120`	`120`	`version_tuple_value(t) > major_minor() and result = 1`
`121`	`121`	`}`
`122`	`122`
`123`		-/* Holds if `cls` is a new-style class if it were to have no explicit base classes */
	`123`	+/** Holds if `cls` is a new-style class if it were to have no explicit base classes */
`124`	`124`	`predicate baseless_is_new_style(ClassObject cls) {`
`125`	`125`	`cls.isBuiltin()`
`126`	`126`	`or`
Original file line number	Diff line number	Diff line change
`@@ -2395,7 +2395,7 @@ module Types {`
`2395`	`2395`	`)`
`2396`	`2396`	`}`
`2397`	`2397`
`2398`		`- /* Holds if type inference failed to compute the full class hierarchy for this class for the reason given. */`
	`2398`	`+ /** Holds if type inference failed to compute the full class hierarchy for this class for the reason given. */`
`2399`	`2399`	`private predicate failedInference(ClassObjectInternal cls, string reason, int priority) {`
`2400`	`2400`	`strictcount(cls.(PythonClassObjectInternal).getScope().getADecorator()) > 1 and`
`2401`	`2401`	`reason = "Multiple decorators" and`
Original file line number	Diff line number	Diff line change
`@@ -166,7 +166,7 @@ class ClassObject extends Object {`
`166`	`166`	`not this.failedInference()`
`167`	`167`	`}`
`168`	`168`
`169`		`- /* Whether this class is abstract. */`
	`169`	`+ /** Holds if this class is abstract. */`
`170`	`170`	`predicate isAbstract() {`
`171`	`171`	`this.getMetaClass() = theAbcMetaClassObject()`
`172`	`172`	`or`