Python: Document a bunch of hasLocationInfo methods.

If only we had been _somewhat consistent in how we named the
parameters for these...

python/ql/src/Lexical/CommentedOutCode.qll

@@ -191,10 +191,19 @@ class CommentedOutCodeBlock extends @py_comment {
     /** The length of this comment block (in comments) */
     int length() { result = count(Comment c | this.contains(c)) }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.(Comment).getLocation().hasLocationInfo(filepath, bl, bc, _, _) and
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        this.(Comment).getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
         exists(Comment end | commented_out_code_block(this, end) |
-            end.getLocation().hasLocationInfo(_, _, _, el, ec)
+            end.getLocation().hasLocationInfo(_, _, _, endline, endcolumn)
         )
     }
 

python/ql/src/Metrics/Internal/Extents.qll

@@ -15,9 +15,17 @@ import python
  * including the body (if any), as opposed to the location of its name only.
  */
 class RangeFunction extends Function {
-    predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
-        super.getLocation().hasLocationInfo(path, sl, sc, _, _) and
-        this.getBody().getLastItem().getLocation().hasLocationInfo(path, _, _, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        super.getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
+        this.getBody().getLastItem().getLocation().hasLocationInfo(filepath, _, _, endline, endcolumn)
     }
 }
 
@@ -26,8 +34,16 @@ class RangeFunction extends Function {
  * including the body (if any), as opposed to the location of its name only.
  */
 class RangeClass extends Class {
-    predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
-        super.getLocation().hasLocationInfo(path, sl, sc, _, _) and
-        this.getBody().getLastItem().getLocation().hasLocationInfo(path, _, _, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        super.getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
+        this.getBody().getLastItem().getLocation().hasLocationInfo(filepath, _, _, endline, endcolumn)
     }
 }

python/ql/src/analysis/DefinitionTracking.qll

@@ -468,7 +468,13 @@ Definition getUniqueDefinition(Expr use) {
 /** Helper class to get suitable locations for attributes */
 class NiceLocationExpr extends @py_expr {
     string toString() { result = this.(Expr).toString() }
-
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `bc` of line `bl` to
+     * column `ec` of line `el` in file `f`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
     predicate hasLocationInfo(string f, int bl, int bc, int el, int ec) {
         /* Attribute location for x.y is that of 'y' so that url does not overlap with that of 'x' */
         exists(int abl, int abc | this.(Attribute).getLocation().hasLocationInfo(f, abl, abc, el, ec) |

python/ql/src/external/DefectFilter.qll

@@ -26,7 +26,9 @@ class DefectResult extends int {
 
     /** Gets the file in which this query result was reported. */
     File getFile() {
-        exists(string path | defectResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path)
+        exists(string path |
+            defectResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path
+        )
     }
 
     /** Gets the file path in which this query result was reported. */
@@ -47,8 +49,17 @@ class DefectResult extends int {
     /** Gets the message associated with this query result. */
     string getMessage() { defectResults(this, _, _, _, _, _, _, result) }
 
-    predicate hasLocationInfo(string path, int sl, int sc, int el, int ec) {
-        defectResults(this, _, path, sl, sc, el, ec, _)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        defectResults(this, _, filepath, startline, startcolumn, endline, endcolumn, _)
     }
 
     /** Gets the URL corresponding to the location of this query result. */

python/ql/src/external/Thrift.qll

@@ -33,12 +33,21 @@ class ThriftElement extends ExternalData {
 
     private int column() { result = this.getFieldAsInt(6) }
 
-    predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
-        fp = this.getPath() and
-        bl = this.line() and
-        bc = this.column() and
-        el = this.line() and
-        ec = this.column() + this.getValue().length() - 1
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        filepath = this.getPath() and
+        startline = this.line() and
+        startcolumn = this.column() and
+        endline = this.line() and
+        endcolumn = this.column() + this.getValue().length() - 1
         or
         exists(ThriftElement first, ThriftElement last |
             first = this.getChild(min(int l | exists(this.getChild(l)))) and
@@ -62,11 +71,11 @@ abstract class ThriftNamedElement extends ThriftElement {
         not exists(this.getName()) and result = this.getKind() + " ???"
     }
 
-    override predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
+    override predicate hasLocationInfo(string filepath, int startline, int startcolumn, int endline, int endcolumn) {
         exists(ThriftElement first |
             first = this.getChild(min(int l | exists(this.getChild(l)))) and
-            first.hasLocationInfo(fp, bl, bc, _, _) and
-            this.getNameElement().hasLocationInfo(fp, _, _, el, ec)
+            first.hasLocationInfo(filepath, startline, startcolumn, _, _) and
+            this.getNameElement().hasLocationInfo(filepath, _, _, endline, endcolumn)
         )
     }
 }
@@ -142,9 +151,9 @@ class ThriftFunction extends ThriftNamedElement {
 
     ThriftType getReturnType() { result = this.getChild(1).getChild(0) }
 
-    override predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
-        this.getChild(1).hasLocationInfo(fp, bl, bc, _, _) and
-        this.getChild(2).hasLocationInfo(fp, _, _, el, ec)
+    override predicate hasLocationInfo(string filepath, int startline, int startcolumn, int endline, int endcolumn) {
+        this.getChild(1).hasLocationInfo(filepath, startline, startcolumn, _, _) and
+        this.getChild(2).hasLocationInfo(filepath, _, _, endline, endcolumn)
     }
 
     ThriftService getService() { result.getAFunction() = this }

python/ql/src/semmle/python/Comment.qll

@@ -56,9 +56,17 @@ class CommentBlock extends @py_comment {
     /** The length of this comment block (in comments) */
     int length() { result = max(int i | comment_block_part(this, _, i)) }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.(Comment).getLocation().hasLocationInfo(filepath, bl, bc, _, _) and
-        exists(Comment end | end = this.last() | end.getLocation().hasLocationInfo(_, _, _, el, ec))
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        this.(Comment).getLocation().hasLocationInfo(filepath, startline, startcolumn, _, _) and
+        exists(Comment end | end = this.last() | end.getLocation().hasLocationInfo(_, _, _, endline, endcolumn))
     }
 
     predicate contains(Comment c) {

python/ql/src/semmle/python/Files.qll

@@ -10,8 +10,21 @@ class File extends Container {
     /** DEPRECATED: Use `getAbsolutePath` instead. */
     deprecated string getFullName() { result = this.getAbsolutePath() }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.getAbsolutePath() = filepath and bl = 0 and bc = 0 and el = 0 and ec = 0
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        this.getAbsolutePath() = filepath and
+        startline = 0 and
+        startcolumn = 0 and
+        endline = 0 and
+        endcolumn = 0
     }
 
     /** Whether this file is a source code file. */
@@ -79,8 +92,21 @@ class Folder extends Container {
     /** DEPRECATED: Use `getBaseName` instead. */
     deprecated string getSimple() { folders(this, _, result) }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.getAbsolutePath() = filepath and bl = 0 and bc = 0 and el = 0 and ec = 0
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        this.getAbsolutePath() = filepath and
+        startline = 0 and
+        startcolumn = 0 and
+        endline = 0 and
+        endcolumn = 0
     }
 
     override string getAbsolutePath() { folders(this, result, _) }
@@ -371,23 +397,39 @@ class Location extends @location {
         result = this.getPath().getAbsolutePath() + ":" + this.getStartLine().toString()
     }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        exists(File f | f.getAbsolutePath() = filepath |
-            locations_default(this, f, bl, bc, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        exists(File f | f.getAbsolutePath() = filepath |
+            locations_default(this, f, startline, startcolumn, endline, endcolumn)
             or
-            exists(Module m | m.getFile() = f | locations_ast(this, m, bl, bc, el, ec))
+            exists(Module m | m.getFile() = f | locations_ast(this, m, startline, startcolumn, endline, endcolumn))
         )
     }
 }
 
 /** A non-empty line in the source code */
 class Line extends @py_line {
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        exists(Module m |
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        exists(Module m |
             m.getFile().getAbsolutePath() = filepath and
-            el = bl and
-            bc = 1 and
-            py_line_lengths(this, m, bl, ec)
+            endline = startline and
+            startcolumn = 1 and
+            py_line_lengths(this, m, startline, endcolumn)
         )
     }
 

python/ql/src/semmle/python/Flow.qll

@@ -1079,9 +1079,17 @@ class BasicBlock extends @py_flow_node {
         this.getASuccessor().reachesExit()
     }
 
-    predicate hasLocationInfo(string file, int line, int col, int endl, int endc) {
-        this.startLocationInfo(file, line, col) and
-        this.endLocationInfo(endl, endc)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        this.startLocationInfo(filepath, startline, startcolumn) and
+        this.endLocationInfo(endline, endcolumn)
     }
 
     /** Gets a true successor to this basic block */

python/ql/src/semmle/python/dataflow/TaintTracking.qll

@@ -378,8 +378,16 @@ abstract class TaintSource extends @py_flow_node {
 
     Location getLocation() { result = this.(ControlFlowNode).getLocation() }
 
-    predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
-        this.getLocation().hasLocationInfo(fp, bl, bc, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        this.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
     }
 
     /** Gets a TaintedNode for this taint source */
@@ -482,8 +490,16 @@ abstract class TaintSink extends @py_flow_node {
 
     Location getLocation() { result = this.(ControlFlowNode).getLocation() }
 
-    predicate hasLocationInfo(string fp, int bl, int bc, int el, int ec) {
-        this.getLocation().hasLocationInfo(fp, bl, bc, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        this.getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
     }
 }
 

python/ql/src/semmle/python/objects/ObjectAPI.qll

@@ -73,15 +73,28 @@ class Value extends TObject {
      */
     predicate isBuiltin() { this.(ObjectInternal).isBuiltin() }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.(ObjectInternal).getOrigin().getLocation().hasLocationInfo(filepath, bl, bc, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {
+        this
+                .(ObjectInternal)
+                .getOrigin()
+                .getLocation()
+                .hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
         or
         not exists(this.(ObjectInternal).getOrigin()) and
         filepath = "" and
-        bl = 0 and
-        bc = 0 and
-        el = 0 and
-        ec = 0
+        startline = 0 and
+        startcolumn = 0 and
+        endline = 0 and
+        endcolumn = 0
     }
 
     /**

python/ql/src/semmle/python/types/Object.qll

@@ -64,15 +64,23 @@ class Object extends @py_object {
 
     private predicate hasOrigin() { py_flow_bb_node(this, _, _, _) }
 
-    predicate hasLocationInfo(string filepath, int bl, int bc, int el, int ec) {
-        this.hasOrigin() and this.getOrigin().getLocation().hasLocationInfo(filepath, bl, bc, el, ec)
+    /**
+     * Holds if this element is at the specified location.
+     * The location spans column `startcolumn` of line `startline` to
+     * column `endcolumn` of line `endline` in file `filepath`.
+     * For more information, see
+     * [Locations](https://help.semmle.com/QL/learn-ql/ql/locations.html).
+     */
+    predicate hasLocationInfo(
+        string filepath, int startline, int startcolumn, int endline, int endcolumn
+    ) {        this.hasOrigin() and this.getOrigin().getLocation().hasLocationInfo(filepath, startline, startcolumn, endline, endcolumn)
         or
         not this.hasOrigin() and
         filepath = ":Compiled Code" and
-        bl = 0 and
-        bc = 0 and
-        el = 0 and
-        ec = 0
+        startline = 0 and
+        startcolumn = 0 and
+        endline = 0 and
+        endcolumn = 0
     }
 
     /** INTERNAL -- Do not use */