Merge pull request #3783 from geoffw0/qldoc2

C++: More QLDoc

Author: jbj

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

@@ -3,7 +3,6 @@
  */
 
 import semmle.code.cpp.Location
-import semmle.code.cpp.Member
 import semmle.code.cpp.Class
 import semmle.code.cpp.Parameter
 import semmle.code.cpp.exprs.Call

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

@@ -1,2 +1,6 @@
+/**
+ * DEPRECATED: import `semmle.code.cpp.Element` and/or `semmle.code.cpp.Type` directly as required.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.Type

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

@@ -1,3 +1,8 @@
+/**
+ * Provides classes for working with name qualifiers such as the `N::` in
+ * `N::f()`.
+ */
+
 import cpp
 
 /**

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

@@ -1,3 +1,7 @@
+/**
+ * Provides classes for modeling namespaces, `using` directives and `using` declarations.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.Type
 import semmle.code.cpp.metrics.MetricNamespace

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

@@ -1,3 +1,8 @@
+/**
+ * Provides a class for reasoning about nested field accesses, for example
+ * the access `myLine.start.x`.
+ */
+
 import cpp
 
 /**
@@ -25,7 +30,7 @@ private Expr getUltimateQualifier(FieldAccess fa) {
 }
 
 /**
- * Accesses to nested fields.
+ * A nested field access, for example the access `myLine.start.x`.
  */
 class NestedFieldAccess extends FieldAccess {
   Expr ultimateQualifier;
@@ -35,6 +40,30 @@ class NestedFieldAccess extends FieldAccess {
     getTarget() = getANestedField(ultimateQualifier.getType().stripType())
   }
 
-  /** Gets the ultimate qualifier of this nested field access. */
+  /**
+   * Gets the outermost qualifier of this nested field access. In the
+   * following example, the access to `myLine.start.x` has outermost qualifier
+   * `myLine`:
+   * ```
+   * struct Point
+   * {
+   *   float x, y;
+   * };
+   *
+   * struct Line
+   * {
+   *   Point start, end;
+   * };
+   *
+   * void init()
+   * {
+   *   Line myLine;
+   *
+   *   myLine.start.x = 0.0f;
+   *
+   *   // ...
+   * }
+   * ```
+   */
   Expr getUltimateQualifier() { result = ultimateQualifier }
 }

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

@@ -1,5 +1,8 @@
+/**
+ * Provides a hierarchy of classes for modeling C/C++ types.
+ */
+
 import semmle.code.cpp.Element
-import semmle.code.cpp.Member
 import semmle.code.cpp.Function
 private import semmle.code.cpp.internal.ResolveClass
 
@@ -1080,22 +1083,46 @@ class DerivedType extends Type, @derivedtype {
 
   override Type stripType() { result = getBaseType().stripType() }
 
-  predicate isAutoReleasing() {
+  /**
+   * Holds if this type has the `__autoreleasing` specifier or if it points to
+   * a type with the `__autoreleasing` specifier.
+   *
+   * DEPRECATED: use `hasSpecifier` directly instead.
+   */
+  deprecated predicate isAutoReleasing() {
     this.hasSpecifier("__autoreleasing") or
     this.(PointerType).getBaseType().hasSpecifier("__autoreleasing")
   }
 
-  predicate isStrong() {
+  /**
+   * Holds if this type has the `__strong` specifier or if it points to
+   * a type with the `__strong` specifier.
+   *
+   * DEPRECATED: use `hasSpecifier` directly instead.
+   */
+  deprecated predicate isStrong() {
     this.hasSpecifier("__strong") or
     this.(PointerType).getBaseType().hasSpecifier("__strong")
   }
 
-  predicate isUnsafeRetained() {
+  /**
+   * Holds if this type has the `__unsafe_unretained` specifier or if it points
+   * to a type with the `__unsafe_unretained` specifier.
+   *
+   * DEPRECATED: use `hasSpecifier` directly instead.
+   */
+  deprecated predicate isUnsafeRetained() {
     this.hasSpecifier("__unsafe_unretained") or
     this.(PointerType).getBaseType().hasSpecifier("__unsafe_unretained")
   }
 
-  predicate isWeak() {
+  /**
+   * Holds if this type has the `__weak` specifier or if it points to
+   * a type with the `__weak` specifier.
+   *
+   * DEPRECATED: use `hasSpecifier` directly instead.
+   */
+  deprecated predicate isWeak() {
     this.hasSpecifier("__weak") or
     this.(PointerType).getBaseType().hasSpecifier("__weak")
   }
@@ -1316,6 +1343,10 @@ class ArrayType extends DerivedType {
 
   override string getCanonicalQLClass() { result = "ArrayType" }
 
+  /**
+   * Holds if this array is declared to be of a constant size. See
+   * `getArraySize` and `getByteSize` to get the size of the array.
+   */
   predicate hasArraySize() { arraysizes(underlyingElement(this), _, _, _) }
 
   /**
@@ -1568,12 +1599,21 @@ class RoutineType extends Type, @routinetype {
 
   override string getName() { result = "..()(..)" }
 
+  /**
+   * Gets the type of the `n`th parameter to this routine.
+   */
   Type getParameterType(int n) {
     routinetypeargs(underlyingElement(this), n, unresolveElement(result))
   }
 
+  /**
+   * Gets the type of a parameter to this routine.
+   */
   Type getAParameterType() { routinetypeargs(underlyingElement(this), _, unresolveElement(result)) }
 
+  /**
+   * Gets the return type of this routine.
+   */
   Type getReturnType() { routinetypes(underlyingElement(this), unresolveElement(result)) }
 
   override string explain() {

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

@@ -1,6 +1,5 @@
 import semmle.code.cpp.Declaration
 import semmle.code.cpp.Type
-import semmle.code.cpp.Member
 import semmle.code.cpp.Function
 private import semmle.code.cpp.internal.ResolveClass
 

cpp/ql/src/semmle/code/cpp/stmts/Block.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides a class to model C/C++ block statements, enclosed by `{` and `}`.
+ */
+
 import semmle.code.cpp.Element
 import semmle.code.cpp.stmts.Stmt
 

cpp/ql/src/semmle/code/cpp/stmts/Stmt.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides a hierarchy of classes for modeling C/C++ statements.
+ */
+
 import semmle.code.cpp.Element
 private import semmle.code.cpp.Enclosing
 private import semmle.code.cpp.internal.ResolveClass