Add comments to new shared APIs.

Author: MichaelRFairhurst

cpp/common/src/codingstandards/cpp/ast/Templates.qll

@@ -0,0 +1,16 @@
+import cpp
+
+/**
+ * A predicate to simplify getting a namespace for a template parameter, since
+ * `TemplateParameterType`'s `getNamespace()` has no result, and `enclosingElement()` has no result,
+ * and there are multiple cases to navigate to work around this.
+ */
+Namespace getTemplateParameterNamespace(TypeTemplateParameter param) {
+  exists(Declaration decl |
+    param = decl.(TemplateClass).getATemplateArgument() or
+    param = decl.(TemplateVariable).getATemplateArgument() or
+    param = decl.(TemplateFunction).getATemplateArgument()
+  |
+    result = decl.getNamespace()
+  )
+}

cpp/common/src/codingstandards/cpp/types/Predicate.qll

@@ -1,27 +1,51 @@
+/**
+ * A library for handling "predicate" types, which are function parameters in the standard library.
+ *
+ * For example, `std::sort` takes a predicate as its third argument, and `std::set` takes a
+ * predicate as its second template parameter. Predicates are always template parameters, and we
+ * can identify them by their name -- this is what MISRA expects us to do.
+ */
+
 import cpp
 private import codingstandards.cpp.StdNamespace
+private import codingstandards.cpp.ast.Templates
 private import codingstandards.cpp.types.Templates
 private import semmle.code.cpp.dataflow.new.DataFlow
 
-Namespace getTemplateParameterNamespace(TypeTemplateParameter param) {
-  exists(Declaration decl |
-    param = decl.(TemplateClass).getATemplateArgument() or
-    param = decl.(TemplateVariable).getATemplateArgument() or
-    param = decl.(TemplateFunction).getATemplateArgument()
-  |
-    result = decl.getNamespace()
-  )
-}
-
+/**
+ * A "predicate" type parameter as defined by MISRA, which is a standard library function named
+ * "Compare" or "Predicate" or "BinaryPredicate" in the standard library.
+ *
+ * To be more widely useful, we match more flexibly on the name, as `_Compare` is also common, etc.
+ *
+ * To get a particular `Type` that is _used_ as a predicate type, see `getASubstitutedType()`,
+ * rather than the type parameter itself, see `getASubstitutedType()`.
+ */
 class PredicateType extends TypeTemplateParameter {
   PredicateType() {
     this.getName().matches(["%Compare%", "%Predicate%"]) and
     getTemplateParameterNamespace(this) instanceof StdNS
   }
 
+  /**
+   * Get a type that is used (anywhere, via some substitution) as this predicate type parameter.
+   *
+   * For example, `std::sort(..., ..., [](int a, int b) { return a < b; })` creates a `Closure`
+   * type, and substitutes that closure type for the predicate type parameter of `std::sort`.
+   */
   Type getASubstitutedType(Substitution sub) { result = sub.getSubstitutedTypeForParameter(this) }
 }
 
+/**
+ * A class type that has been substituted for a predicate type parameter, and has an `operator()`
+ * member function.
+ *
+ * For example, the closure type in `std::sort(..., ..., [](int a, int b) { return a < b; })` is a
+ * `PredicateFunctionObject`, and so is any `std::less<int>` that is used as a predicate type
+ * parameter, etc.
+ *
+ * This does not cover function pointer types, as these are not class types.
+ */
 class PredicateFunctionObject extends Class {
   PredicateType pred;
   Function operator;
@@ -33,13 +57,38 @@ class PredicateFunctionObject extends Class {
     operator.getName() = "operator()"
   }
 
+  /**
+   * Get the predicate type parameter that this function object is being substituted for.
+   */
   PredicateType getPredicateType() { result = pred }
 
+  /**
+   * Get the `operator()` function that this function object defines. This is the function that will
+   * be invoked and essentially defines the predicate behavior.
+   */
   Function getCallOperator() { result = operator }
 
+  /**
+   * Get the `Substitution` object that makes this type a `PredicateFunctionObject`.
+   *
+   * This is a particular instantiation of some template that contains a predicate type parameter,
+   * which is substituted by this type in that instantiation. The `Substitution` object may refer
+   * to a `TemplateClass`, `TemplateVariable`, or `TemplateFunction`.
+   */
   Substitution getSubstitution() { result = sub }
 }
 
+/**
+ * Gets a function access where the purpose of that access is to pass the accessed function as a
+ * predicate argument to a standard library template.
+ *
+ * For example, in `std::sort(..., ..., myCompare)`, where `myCompare` is a function, then
+ * `myCompare` will be converted into a function pointer and that function pointer will be used as
+ * a predicate in that `std::sort` call.
+ *
+ * This is more complex to identify than `PredicateFunctionObject` because the addressee of the
+ * function pointer is not necessarily statically known.
+ */
 class PredicateFunctionPointerUse extends FunctionAccess {
   Expr functionPointerArgument;
   FunctionCall templateFunctionCall;
@@ -62,5 +111,8 @@ class PredicateFunctionPointerUse extends FunctionAccess {
     )
   }
 
+  /**
+   * Get the predicate type parameter that this function pointer is being substituted for.
+   */
   PredicateType getPredicateType() { result = pred }
 }

cpp/common/src/codingstandards/cpp/types/Templates.qll

@@ -5,25 +5,48 @@ private newtype TSubstitution =
   TFunctionSubstitution(FunctionTemplateInstantiation fti) or
   TVariableSubstitution(VariableTemplateInstantiation vti)
 
+/**
+ * A class to facilitate working with template substitutions, especially since templates may be a
+ * `TemplateClass`, `TemplateFunction`, or `TemplateVariable`, which complicates their usage.
+ *
+ * A `Substitution` in particular refers to an instantiation of that template of some kind, and
+ * allows analysis of which parameters were substituted with which types in that instatiation.
+ */
 class Substitution extends TSubstitution {
   ClassTemplateInstantiation asClassSubstitution() { this = TClassSubstitution(result) }
 
   FunctionTemplateInstantiation asFunctionSubstitution() { this = TFunctionSubstitution(result) }
 
   VariableTemplateInstantiation asVariableSubstitution() { this = TVariableSubstitution(result) }
 
+  /**
+   * Get the nth template parameter type of the template that is being substituted.
+   *
+   * For example, in `std::vector<int>`, the 0th template parameter is `typename T`.
+   */
   TypeTemplateParameter getTemplateParameter(int index) {
     result = this.asClassSubstitution().getTemplate().getTemplateArgument(index) or
     result = this.asFunctionSubstitution().getTemplate().getTemplateArgument(index) or
     result = this.asVariableSubstitution().getTemplate().getTemplateArgument(index)
   }
 
+  /**
+   * Get the type that is substituting the nth template parameter in this substitution.
+   *
+   * For example, in `std::vector<int>`, the 0th substituted type is `int`.
+   */
   Type getSubstitutedType(int index) {
     result = this.asClassSubstitution().getTemplateArgument(index) or
     result = this.asFunctionSubstitution().getTemplateArgument(index) or
     result = this.asVariableSubstitution().getTemplateArgument(index)
   }
 
+  /**
+   * Get the type that is substituting the given template parameter in this substitution.
+   *
+   * For example, in `std::vector<int>`, this predicate matches the given type `int` with the type
+   * parameter `typename T`.
+   */
   Type getSubstitutedTypeForParameter(TypeTemplateParameter param) {
     exists(int idx |
       this.getTemplateParameter(idx) = param and
@@ -37,6 +60,14 @@ class Substitution extends TSubstitution {
     result = this.asVariableSubstitution().toString()
   }
 
+  /**
+   * Get a `Locatable` that represents a where this substitution was declared in the source code.
+   *
+   * The result may be a `TypeMention`, `Call`, etc. depending on the kind of template and how it is
+   * being used, but it handles the various template cases for you.
+   *
+   * Note that this instantiation may have been declared in multiple places.
+   */
   Locatable getASubstitutionSite() {
     result.(TypeMention).getMentionedType() = this.asClassSubstitution()
     or