Merge pull request #3808 from geoffw0/qldoc4

C++: Yet more QLDoc

cpp/ql/src/semmle/code/cpp/TestFile.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for identifying files that contain test cases. It is often
+ * desirable to exclude these files from analysis.
+ */
+
 import semmle.code.cpp.File
 
 /**

cpp/ql/src/semmle/code/cpp/commons/StringAnalysis.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides a class for calculating the possible length of string expressions.
+ */
+
 import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.controlflow.SSA
 

cpp/ql/src/semmle/code/cpp/exprs/Access.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for modeling accesses including variable accesses, enum
+ * constant accesses and function accesses.
+ */
+
 import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.Variable
 import semmle.code.cpp.Enum

cpp/ql/src/semmle/code/cpp/exprs/ArithmeticOperation.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for modeling arithmetic operations such as `+`, `-`, `*`
+ * and `++`.
+ */
+
 import semmle.code.cpp.exprs.Expr
 
 /**

cpp/ql/src/semmle/code/cpp/exprs/BitwiseOperation.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for modeling bitwise operations such as `~`, `<<`, `&` and
+ * `|`.
+ */
+
 import semmle.code.cpp.exprs.Expr
 
 /**

cpp/ql/src/semmle/code/cpp/exprs/BuiltInOperations.qll

@@ -1,7 +1,12 @@
+/**
+ * Provides classes for modeling built-in operations.  Built-in operations are
+ * typically compiler specific and are used by libraries and generated code.
+ */
+
 import semmle.code.cpp.exprs.Expr
 
 /**
- * A C/C++ builtin operation. This is the root QL class encompassing
+ * A C/C++ built-in operation. This is the root QL class encompassing
  * built-in functionality.
  */
 class BuiltInOperation extends Expr, @builtin_op {

cpp/ql/src/semmle/code/cpp/exprs/Call.qll

@@ -1,3 +1,9 @@
+/**
+ * Provides classes for modeling call expressions including direct calls to
+ * functions, constructor and destructor calls, and calls made through function
+ * pointers.
+ */
+
 import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.Function
 private import semmle.code.cpp.dataflow.EscapesTree

cpp/ql/src/semmle/code/cpp/exprs/Cast.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for modeling C/C++ casts and conversions, as well as some
+ * type-related operators such as `sizeof` and `alignof`.
+ */
+
 import semmle.code.cpp.exprs.Expr
 private import semmle.code.cpp.internal.ResolveClass
 
@@ -656,6 +661,9 @@ class UuidofOperator extends Expr, @uuidof {
  * ```
  */
 class TypeidOperator extends Expr, @type_id {
+  /**
+   * Gets the type that is returned by this typeid expression.
+   */
   Type getResultType() { typeid_bind(underlyingElement(this), unresolveElement(result)) }
 
   /**

cpp/ql/src/semmle/code/cpp/exprs/ComparisonOperation.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes for modeling comparisons such as `==`, `!=` and `<`.
+ */
+
 import semmle.code.cpp.exprs.Expr
 
 /**

cpp/ql/src/semmle/code/cpp/exprs/Expr.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes modeling C/C++ expressions.
+ */
+
 import semmle.code.cpp.Element
 private import semmle.code.cpp.Enclosing
 private import semmle.code.cpp.internal.ResolveClass

cpp/ql/src/semmle/code/cpp/exprs/Lambda.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides classes for modeling lambda expressions and their captures.
+ */
+
 import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.Class
 

cpp/ql/src/semmle/code/cpp/exprs/LogicalOperation.qll

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for modeling logical operations such as `!`, `&&`, `||`, and
+ * the ternary `? :` expression.
+ */
+
 import semmle.code.cpp.exprs.Expr
 
 /**

cpp/ql/src/semmle/code/cpp/exprs/ObjectiveC.qll

@@ -1,3 +1,7 @@
+/**
+ * DEPRECATED: Objective-C is no longer supported.
+ */
+
 import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.Class
 import semmle.code.cpp.ObjectiveC

cpp/ql/src/semmle/code/cpp/security/PrintfLike.qll

@@ -1,6 +1,18 @@
+/**
+ * Provides a predicate for identifying formatting functions like `printf`.
+ *
+ * Consider using the newer model in
+ * `semmle.code.cpp.models.interfaces.FormattingFunction` directly instead of
+ * this library.
+ */
+
 import semmle.code.cpp.commons.Printf
 import external.ExternalArtifact
 
+/**
+ * Holds if `func` is a `printf`-like formatting function and `formatArg` is
+ * the index of the format string argument.
+ */
 predicate printfLikeFunction(Function func, int formatArg) {
   formatArg = func.(FormattingFunction).getFormatParameterIndex() and
   not func instanceof UserDefinedFormattingFunction