Merge pull request #3593 from rdmarsh2/rdmarsh/cpp/add-qldoc-2

C++: Add QLDoc for AST classes up to Include.qll

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

@@ -1,3 +1,8 @@
+/**
+ * Provides a class and predicate for recognizing files that are likely to have been generated
+ * automatically.
+ */
+
 import semmle.code.cpp.Comments
 import semmle.code.cpp.File
 import semmle.code.cpp.Preprocessor

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing C++ classes, including structs, unions, and template classes.
+ */
+
 import semmle.code.cpp.Type
 import semmle.code.cpp.UserType
 import semmle.code.cpp.metrics.MetricClass

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing C and C++ comments.
+ */
+
 import semmle.code.cpp.Location
 import semmle.code.cpp.Element
 

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

@@ -1,3 +1,7 @@
+/**
+ * Provides a class representing individual compiler invocations that occurred during the build.
+ */
+
 import semmle.code.cpp.File
 
 /*

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes for working with C and C++ declarations.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.Specifier
 import semmle.code.cpp.Namespace

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing warnings generated during compilation.
+ */
+
 import semmle.code.cpp.Location
 
 /** A compiler-generated error, warning or remark. */

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

@@ -1,3 +1,8 @@
+/**
+ * Provides the `Element` class, which is the base class for all classes representing C or C++
+ * program elements.
+ */
+
 import semmle.code.cpp.Location
 private import semmle.code.cpp.Enclosing
 private import semmle.code.cpp.internal.ResolveClass
@@ -261,8 +266,14 @@ private predicate isFromUninstantiatedTemplateRec(Element e, Element template) {
 class StaticAssert extends Locatable, @static_assert {
   override string toString() { result = "static_assert(..., \"" + getMessage() + "\")" }
 
+  /**
+   * Gets the expression which this static assertion ensures is true.
+   */
   Expr getCondition() { static_asserts(underlyingElement(this), unresolveElement(result), _, _) }
 
+  /**
+   * Gets the message which will be reported by the compiler if this static assertion fails.
+   */
   string getMessage() { static_asserts(underlyingElement(this), _, result, _) }
 
   override Location getLocation() { static_asserts(underlyingElement(this), _, _, result) }

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

@@ -1,3 +1,7 @@
+/**
+ * Provides predicates for finding the smallest element that encloses an expression or statement.
+ */
+
 import cpp
 
 /**

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing C/C++ enums and enum constants.
+ */
+
 import semmle.code.cpp.Type
 private import semmle.code.cpp.internal.ResolveClass
 
@@ -19,6 +23,17 @@ class Enum extends UserType, IntegralOrEnumType {
   /** Gets an enumerator of this enumeration. */
   EnumConstant getAnEnumConstant() { result.getDeclaringEnum() = this }
 
+  /**
+   * Gets the enumerator of this enumeration that was declared at the zero-based position `index`.
+   * For example, `zero` is at index 2 in the following declaration:
+   * ```
+   * enum ReversedOrder {
+   *   two = 2,
+   *   one = 1,
+   *   zero = 0
+   * };
+   * ```
+   */
   EnumConstant getEnumConstant(int index) {
     enumconstants(unresolveElement(result), underlyingElement(this), index, _, _, _)
   }

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing C structure members and C++ non-static member variables.
+ */
+
 import semmle.code.cpp.Variable
 import semmle.code.cpp.Enum
 import semmle.code.cpp.exprs.Access

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes representing files and folders.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.Declaration
 import semmle.code.cpp.metrics.MetricFile

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

@@ -1,3 +1,7 @@
+/**
+ * Provides a class representing C++ `friend` declarations.
+ */
+
 import semmle.code.cpp.Declaration
 private import semmle.code.cpp.internal.ResolveClass
 

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

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for working with functions, including C++ constructors, destructors,
+ * user-defined operators, and template functions.
+ */
+
 import semmle.code.cpp.Location
 import semmle.code.cpp.Member
 import semmle.code.cpp.Class
@@ -891,8 +896,10 @@ class Constructor extends MemberFunction {
  * A function that defines an implicit conversion.
  */
 abstract class ImplicitConversionFunction extends MemberFunction {
+  /** Gets the type this `ImplicitConversionFunction` takes as input. */
   abstract Type getSourceType();
 
+  /** Gets the type this `ImplicitConversionFunction` converts to. */
   abstract Type getDestType();
 }
 

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

@@ -1,3 +1,8 @@
+/**
+ * Provides classes representing C/C++ `#include`, `#include_next`, and `#import` preprocessor
+ * directives.
+ */
+
 import semmle.code.cpp.Preprocessor
 
 /**