Python: Clarify comment about 'syntax:' comment and add ... to for and async for comments.

Author: markshannon

python/ql/src/semmle/python/AstExtended.qll

@@ -3,8 +3,10 @@ import python
 /** Syntactic node (Class, Function, Module, Expr, Stmt or Comprehension) corresponding to a flow node */
 abstract class AstNode extends AstNode_ {
 
-    /* Special comment for documentation generation */
-    /* syntax: */
+    /* Special comment for documentation generation.
+     * All subclasses of `AstNode` that represent concrete syntax should have
+     * a comment of the form: */
+    /* syntax: ... */
 
     /** Gets the scope that this node occurs in */
     abstract Scope getScope();

python/ql/src/semmle/python/Exprs.qll

@@ -131,7 +131,6 @@ class Expr extends Expr_, AstNode {
 /** An attribute expression, such as `value.attr` */
 class Attribute extends Attribute_ {
 
-    /* Special comment for documentation generation */
     /* syntax: Expr.name */
 
     override Expr getASubExpression() {
@@ -481,7 +480,6 @@ class FloatLiteral extends Num {
 class ImaginaryLiteral extends Num {
     private float value;
 
-    /* Special comment for documentation generation */
     /* syntax: 1.0j */
 
     ImaginaryLiteral() {
@@ -541,7 +539,6 @@ class NegativeIntegerLiteral extends ImmutableLiteral, UnaryExpr {
    "hello" are treated as Bytes for Python2, but Unicode for Python3. */
 class Unicode extends StrConst {
 
-    /* Special comment for documentation generation */
     /* syntax: "hello" */
 
     Unicode() {
@@ -572,7 +569,6 @@ class Unicode extends StrConst {
 /** A dictionary expression, such as `{'key':'value'}` */
 class Dict extends Dict_ {
 
-    /* Special comment for documentation generation */
     /* syntax: {Expr: Expr, ...} */
 
     /** Gets the value of an item of this dict display */
@@ -600,7 +596,6 @@ class Dict extends Dict_ {
 /** A list expression, such as `[ 1, 3, 5, 7, 9 ]` */
 class List extends List_ {
 
-    /* Special comment for documentation generation */
     /* syntax: [Expr, ...] */
 
     override Expr getASubExpression() {
@@ -612,7 +607,6 @@ class List extends List_ {
 /** A set expression such as `{ 1, 3, 5, 7, 9 }` */
 class Set extends Set_ {
 
-    /* Special comment for documentation generation */
     /* syntax: {Expr, ...} */
 
     override Expr getASubExpression() {
@@ -749,7 +743,6 @@ class Slice extends Slice_ {
 /** A string constant. */
 class StrConst extends Str_, ImmutableLiteral {
 
-    /* Special comment for documentation generation */
     /* syntax: "hello" */
 
     predicate isUnicode() {
@@ -837,7 +830,6 @@ abstract class BooleanLiteral extends NameConstant {
 /** The boolean named constant `True` */
 class True extends BooleanLiteral {
 
-    /* Special comment for documentation generation */
     /* syntax: True */
 
     True() {
@@ -857,7 +849,6 @@ class True extends BooleanLiteral {
 /** The boolean named constant `False` */
 class False extends BooleanLiteral {
 
-    /* Special comment for documentation generation */
     /* syntax: False */
 
     False() {
@@ -877,7 +868,6 @@ class False extends BooleanLiteral {
 /** `None` */
 class None extends NameConstant {
 
-    /* Special comment for documentation generation */
     /* syntax: None */
 
     None() {
@@ -896,7 +886,6 @@ class None extends NameConstant {
 /** An await expression such as `await coro`. */
 class Await extends Await_ {
 
-    /* Special comment for documentation generation */
     /* syntax: await Expr */
 
     override Expr getASubExpression() {

python/ql/src/semmle/python/Stmts.qll

@@ -98,7 +98,6 @@ class Assign extends Assign_ {
 /** An assignment statement */
 class AssignStmt extends Assign {
 
-    /* Special comment for documentation generation */
     /* syntax: Expr, ... = Expr */
 
     AssignStmt() {
@@ -281,7 +280,7 @@ class ExprStmt extends ExprStmt_ {
 /** A for statement, such as `for x in y: print(x)` */
 class For extends For_ {
 
-    /* syntax: for varname in Expr: */
+    /* syntax: for varname in Expr: ... */
 
     override Stmt getASubStatement() {
         result = this.getAStmt() or
@@ -569,7 +568,7 @@ class TemplateWrite extends TemplateWrite_ {
 
 class AsyncFor extends For {
 
-    /* syntax: async for varname in Expr: */
+    /* syntax: async for varname in Expr: ... */
 
     AsyncFor() {
         this.isAsync()