C++/JavaScript: Improve CodeDuplication.qll QLDoc

cpp/ql/src/external/CodeDuplication.qll

@@ -1,3 +1,5 @@
+/** Provides classes for detecting duplicate or similar code. */
+
 import cpp
 
 private string relativePath(File file) { result = file.getRelativePath().replaceAll("\\", "/") }
@@ -8,41 +10,59 @@ private predicate tokenLocation(string path, int sl, int sc, int ec, int el, Cop
   tokens(copy, index, sl, sc, ec, el)
 }
 
+/** A token block used for detection of duplicate and similar code. */
 class Copy extends @duplication_or_similarity {
+  /** Gets the index of the last token in this block. */
   private int lastToken() { result = max(int i | tokens(this, i, _, _, _, _) | i) }
 
+  /** Gets the index of the token in this block starting at the location `loc`, if any. */
   int tokenStartingAt(Location loc) {
     exists(string filepath, int startline, int startcol |
       loc.hasLocationInfo(filepath, startline, startcol, _, _) and
       tokenLocation(filepath, startline, startcol, _, _, this, result)
     )
   }
 
+  /** Gets the index of the token in this block ending at the location `loc`, if any. */
   int tokenEndingAt(Location loc) {
     exists(string filepath, int endline, int endcol |
       loc.hasLocationInfo(filepath, _, _, endline, endcol) and
       tokenLocation(filepath, _, _, endline, endcol, this, result)
     )
   }
 
+  /** Gets the line on which the first token in this block starts. */
   int sourceStartLine() { tokens(this, 0, result, _, _, _) }
 
+  /** Gets the column on which the first token in this block starts. */
   int sourceStartColumn() { tokens(this, 0, _, result, _, _) }
 
+  /** Gets the line on which the last token in this block ends. */
   int sourceEndLine() { tokens(this, lastToken(), _, _, result, _) }
 
+  /** Gets the column on which the last token in this block ends. */
   int sourceEndColumn() { tokens(this, lastToken(), _, _, _, result) }
 
+  /** Gets the number of lines containing at least (part of) one token in this block. */
   int sourceLines() { result = this.sourceEndLine() + 1 - this.sourceStartLine() }
 
+  /** Gets an opaque identifier for the equivalence class of this block. */
   int getEquivalenceClass() { duplicateCode(this, _, result) or similarCode(this, _, result) }
 
+  /** Gets the source file in which this block appears. */
   File sourceFile() {
     exists(string name | duplicateCode(this, name, _) or similarCode(this, name, _) |
       name.replaceAll("\\", "/") = relativePath(result)
     )
   }
 
+  /**
+   * 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
   ) {
@@ -53,25 +73,30 @@ class Copy extends @duplication_or_similarity {
     endcolumn = sourceEndColumn()
   }
 
+  /** Gets a textual representation of this element. */
   string toString() { none() }
 }
 
+/** A block of duplicated code. */
 class DuplicateBlock extends Copy, @duplication {
   override string toString() { result = "Duplicate code: " + sourceLines() + " duplicated lines." }
 }
 
+/** A block of similar code. */
 class SimilarBlock extends Copy, @similarity {
   override string toString() {
     result = "Similar code: " + sourceLines() + " almost duplicated lines."
   }
 }
 
+/** Gets a function with a body and a location. */
 FunctionDeclarationEntry sourceMethod() {
   result.isDefinition() and
   exists(result.getLocation()) and
   numlines(unresolveElement(result.getFunction()), _, _, _)
 }
 
+/** Gets the number of member functions in `c` with a body and a location. */
 int numberOfSourceMethods(Class c) {
   result =
     count(FunctionDeclarationEntry m |
@@ -108,20 +133,27 @@ private predicate duplicateStatement(
   )
 }
 
+/**
+ * Holds if `m1` is a function with `total` lines, and `m2` is a function
+ * that has `duplicate` lines in common with `m1`.
+ */
 predicate duplicateStatements(
   FunctionDeclarationEntry m1, FunctionDeclarationEntry m2, int duplicate, int total
 ) {
   duplicate = strictcount(Stmt s | duplicateStatement(m1, m2, s, _)) and
   total = strictcount(statementInMethod(m1))
 }
 
-/**
- * Find pairs of methods are identical
- */
+/** Holds if `m` and other are identical functions. */
 predicate duplicateMethod(FunctionDeclarationEntry m, FunctionDeclarationEntry other) {
   exists(int total | duplicateStatements(m, other, total, total))
 }
 
+/**
+ * INTERNAL: do not use.
+ *
+ * Holds if `line` in `f` is similar to a line somewhere else.
+ */
 predicate similarLines(File f, int line) {
   exists(SimilarBlock b | b.sourceFile() = f and line in [b.sourceStartLine() .. b.sourceEndLine()])
 }
@@ -152,6 +184,7 @@ private predicate similarLinesCoveredFiles(File f, File otherFile) {
   )
 }
 
+/** Holds if `coveredLines` lines of `f` are similar to lines in `otherFile`. */
 predicate similarLinesCovered(File f, int coveredLines, File otherFile) {
   exists(int numLines | numLines = f.getMetrics().getNumberOfLines() |
     similarLinesCoveredFiles(f, otherFile) and
@@ -166,6 +199,11 @@ predicate similarLinesCovered(File f, int coveredLines, File otherFile) {
   )
 }
 
+/**
+ * INTERNAL: do not use.
+ *
+ * Holds if `line` in `f` is duplicated by a line somewhere else.
+ */
 predicate duplicateLines(File f, int line) {
   exists(DuplicateBlock b |
     b.sourceFile() = f and line in [b.sourceStartLine() .. b.sourceEndLine()]
@@ -182,6 +220,7 @@ private predicate duplicateLinesPerEquivalenceClass(int equivClass, int lines, F
     )
 }
 
+/** Holds if `coveredLines` lines of `f` are duplicates of lines in `otherFile`. */
 predicate duplicateLinesCovered(File f, int coveredLines, File otherFile) {
   exists(int numLines | numLines = f.getMetrics().getNumberOfLines() |
     exists(int coveredApprox |
@@ -206,6 +245,7 @@ predicate duplicateLinesCovered(File f, int coveredLines, File otherFile) {
   )
 }
 
+/** Holds if most of `f` (`percent`%) is similar to `other`. */
 predicate similarFiles(File f, File other, int percent) {
   exists(int covered, int total |
     similarLinesCovered(f, covered, other) and
@@ -216,6 +256,7 @@ predicate similarFiles(File f, File other, int percent) {
   not duplicateFiles(f, other, _)
 }
 
+/** Holds if most of `f` (`percent`%) is duplicated by `other`. */
 predicate duplicateFiles(File f, File other, int percent) {
   exists(int covered, int total |
     duplicateLinesCovered(f, covered, other) and
@@ -225,6 +266,10 @@ predicate duplicateFiles(File f, File other, int percent) {
   )
 }
 
+/**
+ * Holds if most member functions of `c` (`numDup` out of `total`) are
+ * duplicates of member functions in `other`.
+ */
 predicate mostlyDuplicateClassBase(Class c, Class other, int numDup, int total) {
   numDup =
     strictcount(FunctionDeclarationEntry m1 |
@@ -240,6 +285,11 @@ predicate mostlyDuplicateClassBase(Class c, Class other, int numDup, int total)
   (numDup * 100) / total > 80
 }
 
+/**
+ * Holds if most member functions of `c` are duplicates of member functions in
+ * `other`. Provides the human-readable `message` to describe the amount of
+ * duplication.
+ */
 predicate mostlyDuplicateClass(Class c, Class other, string message) {
   exists(int numDup, int total |
     mostlyDuplicateClassBase(c, other, numDup, total) and
@@ -264,12 +314,21 @@ predicate mostlyDuplicateClass(Class c, Class other, string message) {
   )
 }
 
+/** Holds if `f` and `other` are similar or duplicates. */
 predicate fileLevelDuplication(File f, File other) {
   similarFiles(f, other, _) or duplicateFiles(f, other, _)
 }
 
+/**
+ * Holds if most member functions of `c` are duplicates of member functions in
+ * `other`.
+ */
 predicate classLevelDuplication(Class c, Class other) { mostlyDuplicateClass(c, other, _) }
 
+/**
+ * Holds if `line` in `f` should be allowed to be duplicated. This is the case
+ * for `#include` directives.
+ */
 predicate whitelistedLineForDuplication(File f, int line) {
   exists(Include i | i.getFile() = f and i.getLocation().getStartLine() = line)
 }

javascript/ql/src/external/CodeDuplication.qll

@@ -261,6 +261,11 @@ predicate similarContainers(StmtContainer sc, StmtContainer other, float percent
   )
 }
 
+/**
+ * INTERNAL: do not use.
+ *
+ * Holds if `line` in `f` is similar to a line somewhere else.
+ */
 predicate similarLines(File f, int line) {
   exists(SimilarBlock b | b.sourceFile() = f and line in [b.sourceStartLine() .. b.sourceEndLine()])
 }
@@ -275,6 +280,7 @@ private predicate similarLinesPerEquivalenceClass(int equivClass, int lines, Fil
     )
 }
 
+/** Holds if `coveredLines` lines of `f` are similar to lines in `otherFile`. */
 pragma[noopt]
 private predicate similarLinesCovered(File f, int coveredLines, File otherFile) {
   exists(int numLines | numLines = f.getNumberOfLines() |
@@ -296,6 +302,11 @@ private predicate similarLinesCovered(File f, int coveredLines, File otherFile)
   )
 }
 
+/**
+ * INTERNAL: do not use.
+ *
+ * Holds if `line` in `f` is duplicated by a line somewhere else.
+ */
 predicate duplicateLines(File f, int line) {
   exists(DuplicateBlock b |
     b.sourceFile() = f and line in [b.sourceStartLine() .. b.sourceEndLine()]
@@ -312,6 +323,7 @@ private predicate duplicateLinesPerEquivalenceClass(int equivClass, int lines, F
     )
 }
 
+/** Holds if `coveredLines` lines of `f` are duplicates of lines in `otherFile`. */
 pragma[noopt]
 private predicate duplicateLinesCovered(File f, int coveredLines, File otherFile) {
   exists(int numLines | numLines = f.getNumberOfLines() |
@@ -333,6 +345,7 @@ private predicate duplicateLinesCovered(File f, int coveredLines, File otherFile
   )
 }
 
+/** Holds if most of `f` (`percent`%) is similar to `other`. */
 predicate similarFiles(File f, File other, int percent) {
   exists(int covered, int total |
     similarLinesCovered(f, covered, other) and
@@ -343,6 +356,7 @@ predicate similarFiles(File f, File other, int percent) {
   not duplicateFiles(f, other, _)
 }
 
+/** Holds if most of `f` (`percent`%) is duplicated by `other`. */
 predicate duplicateFiles(File f, File other, int percent) {
   exists(int covered, int total |
     duplicateLinesCovered(f, covered, other) and