Merge pull request github#3822 from tausbn/python-document-internal-ast-classes

Python: Document internal AST classes.

Author: yoff

python/ql/src/Lexical/CommentedOutCode.qll

@@ -175,6 +175,7 @@ class CommentedOutCodeLine extends Comment {
 class CommentedOutCodeBlock extends @py_comment {
     CommentedOutCodeBlock() { commented_out_code_block(this, _) }
 
+    /** Gets a textual representation of this element. */
     string toString() { result = "Commented out code" }
 
     /** Whether this commented-out code block contains the comment c */

python/ql/src/analysis/DefinitionTracking.qll

@@ -10,6 +10,7 @@ private newtype TDefinition =
 
 /** A definition for the purposes of jump-to-definition. */
 class Definition extends TLocalDefinition {
+    /** Gets a textual representation of this element. */
     string toString() { result = "Definition " + this.getAstNode().getLocation().toString() }
 
     AstNode getAstNode() { this = TLocalDefinition(result) }
@@ -467,6 +468,7 @@ Definition getUniqueDefinition(Expr use) {
 
 /** Helper class to get suitable locations for attributes */
 class NiceLocationExpr extends @py_expr {
+    /** Gets a textual representation of this element. */
     string toString() { result = this.(Expr).toString() }
     /**
      * Holds if this element is at the specified location.

python/ql/src/external/ExternalArtifact.qll

@@ -18,6 +18,7 @@ class ExternalDefect extends @externalDefect {
 
     Location getLocation() { externalDefects(this, _, result, _, _) }
 
+    /** Gets a textual representation of this element. */
     string toString() { result = getQueryPath() + ": " + getLocation() + " - " + getMessage() }
 }
 
@@ -28,6 +29,7 @@ class ExternalMetric extends @externalMetric {
 
     Location getLocation() { externalMetrics(this, _, result, _) }
 
+    /** Gets a textual representation of this element. */
     string toString() { result = getQueryPath() + ": " + getLocation() + " - " + getValue() }
 }
 

python/ql/src/external/VCS.qll

@@ -10,6 +10,7 @@ class Commit extends @svnentry {
         )
     }
 
+    /** Gets a textual representation of this element. */
     string toString() { result = this.getRevisionName() }
 
     string getRevisionName() { svnentries(this, result, _, _, _) }