Merge pull request github#3557 from jbj/qldoc-external

C++: QLDoc for legacy libraries in `external` dir

Author: geoffw0

cpp/ql/src/external/DefectFilter.qll

@@ -1,31 +1,52 @@
+/** Provides a class for working with defect query results stored in dashboard databases. */
+
 import cpp
 
+/**
+ * Holds if `id` in the opaque identifier of a result reported by query `queryPath`,
+ * such that `message` is the associated message and the location of the result 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).
+ */
 external predicate defectResults(
   int id, string queryPath, string file, int startline, int startcol, int endline, int endcol,
   string message
 );
 
+/**
+ * A defect query result stored in a dashboard database.
+ */
 class DefectResult extends int {
   DefectResult() { defectResults(this, _, _, _, _, _, _, _) }
 
+  /** Gets the path of the query that reported the result. */
   string getQueryPath() { defectResults(this, result, _, _, _, _, _, _) }
 
+  /** Gets the file in which this query result was reported. */
   File getFile() {
     exists(string path |
       defectResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path
     )
   }
 
+  /** Gets the line on which the location of this query result starts. */
   int getStartLine() { defectResults(this, _, _, result, _, _, _, _) }
 
+  /** Gets the column on which the location of this query result starts. */
   int getStartColumn() { defectResults(this, _, _, _, result, _, _, _) }
 
+  /** Gets the line on which the location of this query result ends. */
   int getEndLine() { defectResults(this, _, _, _, _, result, _, _) }
 
+  /** Gets the column on which the location of this query result ends. */
   int getEndColumn() { defectResults(this, _, _, _, _, _, result, _) }
 
+  /** Gets the message associated with this query result. */
   string getMessage() { defectResults(this, _, _, _, _, _, _, result) }
 
+  /** Gets the URL corresponding to the location of this query result. */
   string getURL() {
     result =
       "file://" + getFile().getAbsolutePath() + ":" + getStartLine() + ":" + getStartColumn() + ":" +

cpp/ql/src/external/ExternalArtifact.qll

@@ -1,26 +1,45 @@
+/**
+ * Provides classes for working with external data.
+ */
+
 import cpp
 
+/**
+ * An external data item.
+ */
 class ExternalData extends @externalDataElement {
+  /** Gets the path of the file this data was loaded from. */
   string getDataPath() { externalData(this, result, _, _) }
 
+  /**
+   * Gets the path of the file this data was loaded from, with its
+   * extension replaced by `.ql`.
+   */
   string getQueryPath() { result = getDataPath().regexpReplaceAll("\\.[^.]*$", ".ql") }
 
+  /** Gets the number of fields in this data item. */
   int getNumFields() { result = 1 + max(int i | externalData(this, _, i, _) | i) }
 
-  string getField(int index) { externalData(this, _, index, result) }
+  /** Gets the value of the `i`th field of this data item. */
+  string getField(int i) { externalData(this, _, i, result) }
 
-  int getFieldAsInt(int index) { result = getField(index).toInt() }
+  /** Gets the integer value of the `i`th field of this data item. */
+  int getFieldAsInt(int i) { result = getField(i).toInt() }
 
-  float getFieldAsFloat(int index) { result = getField(index).toFloat() }
+  /** Gets the floating-point value of the `i`th field of this data item. */
+  float getFieldAsFloat(int i) { result = getField(i).toFloat() }
 
-  date getFieldAsDate(int index) { result = getField(index).toDate() }
+  /** Gets the value of the `i`th field of this data item, interpreted as a date. */
+  date getFieldAsDate(int i) { result = getField(i).toDate() }
 
+  /** Gets a textual representation of this data item. */
   string toString() { result = getQueryPath() + ": " + buildTupleString(0) }
 
-  private string buildTupleString(int start) {
-    start = getNumFields() - 1 and result = getField(start)
+  /** Gets a textual representation of this data item, starting with the `n`th field. */
+  private string buildTupleString(int n) {
+    n = getNumFields() - 1 and result = getField(n)
     or
-    start < getNumFields() - 1 and result = getField(start) + "," + buildTupleString(start + 1)
+    n < getNumFields() - 1 and result = getField(n) + "," + buildTupleString(n + 1)
   }
 }
 
@@ -33,7 +52,9 @@ class DefectExternalData extends ExternalData {
     this.getNumFields() = 2
   }
 
+  /** Gets the URL associated with this data item. */
   string getURL() { result = getField(0) }
 
+  /** Gets the message associated with this data item. */
   string getMessage() { result = getField(1) }
 }

cpp/ql/src/external/MetricFilter.qll

@@ -1,31 +1,58 @@
+/** Provides a class for working with metric query results stored in dashboard databases. */
+
 import cpp
 
+/**
+ * Holds if `id` in the opaque identifier of a result reported by query `queryPath`,
+ * such that `value` is the reported metric value and the location of the result 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).
+ */
 external predicate metricResults(
   int id, string queryPath, string file, int startline, int startcol, int endline, int endcol,
   float value
 );
 
+/**
+ * A metric query result stored in a dashboard database.
+ */
 class MetricResult extends int {
   MetricResult() { metricResults(this, _, _, _, _, _, _, _) }
 
+  /** Gets the path of the query that reported the result. */
   string getQueryPath() { metricResults(this, result, _, _, _, _, _, _) }
 
+  /** Gets the file in which this query result was reported. */
   File getFile() {
     exists(string path |
       metricResults(this, _, path, _, _, _, _, _) and result.getAbsolutePath() = path
     )
   }
 
+  /** Gets the line on which the location of this query result starts. */
   int getStartLine() { metricResults(this, _, _, result, _, _, _, _) }
 
+  /** Gets the column on which the location of this query result starts. */
   int getStartColumn() { metricResults(this, _, _, _, result, _, _, _) }
 
+  /** Gets the line on which the location of this query result ends. */
   int getEndLine() { metricResults(this, _, _, _, _, result, _, _) }
 
+  /** Gets the column on which the location of this query result ends. */
   int getEndColumn() { metricResults(this, _, _, _, _, _, result, _) }
 
+  /**
+   * Holds if there is a `Location` entity whose location is the same as
+   * the location of this query result.
+   */
   predicate hasMatchingLocation() { exists(this.getMatchingLocation()) }
 
+  /**
+   * Gets the `Location` entity whose location is the same as the location
+   * of this query result.
+   */
   Location getMatchingLocation() {
     result.getFile() = this.getFile() and
     result.getStartLine() = this.getStartLine() and
@@ -34,8 +61,10 @@ class MetricResult extends int {
     result.getEndColumn() = this.getEndColumn()
   }
 
+  /** Gets the value associated with this query result. */
   float getValue() { metricResults(this, _, _, _, _, _, _, result) }
 
+  /** Gets the URL corresponding to the location of this query result. */
   string getURL() {
     result =
       "file://" + getFile().getAbsolutePath() + ":" + getStartLine() + ":" + getStartColumn() + ":" +