Merge pull request #3256 from Semmle/rdmarsh/cpp/add-qldoc-1

C++: Add QLdoc to some AST methods (Class.qll-Diagnostics.qll)

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

@@ -458,6 +458,15 @@ class Class extends UserType {
     exists(ClassDerivation d | d.getDerivedClass() = this and d = result)
   }
 
+  /**
+   * Gets class derivation number `index` of this class/struct, for example the
+   * `public B` is derivation 1 in the following code:
+   * ```
+   * class D : public A, public B, public C {
+   *   ...
+   * };
+   * ```
+   */
   ClassDerivation getDerivation(int index) {
     exists(ClassDerivation d | d.getDerivedClass() = this and d.getIndex() = index and d = result)
   }
@@ -900,6 +909,22 @@ class AbstractClass extends Class {
 class TemplateClass extends Class {
   TemplateClass() { usertypes(underlyingElement(this), _, 6) }
 
+  /**
+   * Gets a class instantiated from this template.
+   *
+   * For example for `MyTemplateClass<T>` in the following code, the results are
+   * `MyTemplateClass<int>` and `MyTemplateClass<long>`:
+   * ```
+   * template<class T>
+   * class MyTemplateClass {
+   *   ...
+   * };
+   *
+   * MyTemplateClass<int> instance;
+   *
+   * MyTemplateClass<long> instance;
+   * ```
+   */
   Class getAnInstantiation() {
     result.isConstructedFrom(this) and
     exists(result.getATemplateArgument())

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

@@ -13,8 +13,20 @@ class Comment extends Locatable, @comment {
 
   override Location getLocation() { comments(underlyingElement(this), _, result) }
 
+  /**
+   * Gets the text of this comment, including the opening `//` or `/*`, and the closing `*``/` if
+   * present.
+   */
   string getContents() { comments(underlyingElement(this), result, _) }
 
+  /**
+   * Gets the AST element this comment is associated with. For example, the comment in the
+   * following code is associated with the declaration of `j`.
+   * ```
+   * int i;
+   * int j; // Comment on j
+   * ```
+   */
   Element getCommentedElement() {
     commentbinding(underlyingElement(this), unresolveElement(result))
   }

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

@@ -40,6 +40,7 @@ class Compilation extends @compilation {
   /** Gets a file compiled during this invocation. */
   File getAFileCompiled() { result = getFileCompiled(_) }
 
+  /** Gets the `i`th file compiled during this invocation */
   File getFileCompiled(int i) { compilation_compiling_files(this, i, unresolveElement(result)) }
 
   /**

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

@@ -11,6 +11,7 @@ class Diagnostic extends Locatable, @diagnostic {
   /** Gets the error code for this compiler message. */
   string getTag() { diagnostics(underlyingElement(this), _, result, _, _, _) }
 
+  /** Holds if `s` is the error code for this compiler message. */
   predicate hasTag(string s) { this.getTag() = s }
 
   /**