CPP: Examples Access.qll.

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

@@ -18,7 +18,18 @@ abstract class Access extends Expr, NameQualifiableElement {
 }
 
 /**
- * A C/C++ enum constant access expression.
+ * A C/C++ enum constant access expression. For example the access to
+ * `MYENUMCONST1` in `myFunction` in the following code:
+ * ```
+ * enum MyEnum {
+ *   MYENUMCONST1,
+ *   MYENUMCONST2
+ * };
+ *
+ * void myFunction() {
+ *   MyEnum v = MYENUMCONST1;
+ * };
+ * ```
  */
 class EnumConstantAccess extends Access, @varaccess {
   override string getCanonicalQLClass() { result = "EnumConstantAccess" }
@@ -35,7 +46,15 @@ class EnumConstantAccess extends Access, @varaccess {
 }
 
 /**
- * A C/C++ variable access expression.
+ * A C/C++ variable access expression. For example the accesses to
+ * `x` and `y` in `myFunction` in the following code:
+ * ```
+ * int x;
+ *
+ * void myFunction(int y) {
+ *   x = y;
+ * };
+ * ```
  */
 class VariableAccess extends Access, @varaccess {
   override string getCanonicalQLClass() { result = "VariableAccess" }
@@ -129,7 +148,18 @@ class VariableAccess extends Access, @varaccess {
 }
 
 /**
- * A C/C++ field access expression.
+ * A C/C++ field access expression. For example the accesses to
+ * `x` and `y` in `myMethod` in the following code:
+ * ```
+ * class MyClass {
+ * public:
+ *   void myMethod(MyClass &other) {
+ *     x = other.y;
+ *   }
+ *
+ *   int x, y;
+ * };
+ * ```
  */
 class FieldAccess extends VariableAccess {
   override string getCanonicalQLClass() { result = "FieldAccess" }
@@ -141,8 +171,20 @@ class FieldAccess extends VariableAccess {
 }
 
 /**
- * A field access of the form `obj->field`. The type of `obj` is a pointer,
- * so this is equivalent to `(*obj).field`.
+ * A field access whose qualifier is a pointer to a class, struct or union.
+ * These typically take the form `obj->field`, but also includes many accesses
+ * with an implicit `this->` qualifier. For example the accesses to `x` and
+ * `y` in `myMethod` in the following code:
+ * ```
+ * class MyClass {
+ * public:
+ *   void myMethod(MyClass *other) {
+       other->x = y;
+ *   }
+ *
+ *   int x, y;
+ * };
+ * ```
  */
 class PointerFieldAccess extends FieldAccess {
   override string getCanonicalQLClass() { result = "PointerFieldAccess" }
@@ -169,7 +211,18 @@ class DotFieldAccess extends FieldAccess {
 
 /**
  * A field access of the form `obj.field`, where the type of `obj` is a
- * reference to a class/struct/union.
+ * reference to a class/struct/union. For example the accesses to `y` in
+ * `myMethod` in the following code:
+ * ```
+ * class MyClass {
+ * public:
+ *   void myMethod(MyClass a, MyClass &b) {
+ *     a.x = b.y;
+ *   }
+ *
+ *   int x, y;
+ * };
+ * ```
  */
 class ReferenceFieldAccess extends DotFieldAccess {
   override string getCanonicalQLClass() { result = "ReferenceFieldAccess" }
@@ -179,7 +232,18 @@ class ReferenceFieldAccess extends DotFieldAccess {
 
 /**
  * A field access of the form `obj.field`, where the type of `obj` is a
- * class/struct/union (and not a reference).
+ * class/struct/union (and not a reference). For example the accesses to `x`
+ * in `myMethod` in the following code:
+ * ```
+ * class MyClass {
+ * public:
+ *   void myMethod(MyClass a, MyClass &b) {
+ *     a.x = b.y;
+ *   }
+ *
+ *   int x, y;
+ * };
+ * ```
  */
 class ValueFieldAccess extends DotFieldAccess {
   override string getCanonicalQLClass() { result = "ValueFieldAccess" }
@@ -198,20 +262,18 @@ private predicate referenceConversion(Conversion c) {
 /**
  * Holds if `e` is a reference expression (that is, it has a type of the
  * form `T&`), which is converted to a value. For example:
- *
  * ```
  * int myfcn(MyStruct &x) {
  *   return x.field;
  * }
  * ```
- *
  * In this example, the type of `x` is `MyStruct&`, but it gets implicitly
  * converted to `MyStruct` in the expression `x.field`.
  */
 private predicate exprHasReferenceConversion(Expr e) { referenceConversion(e.getConversion+()) }
 
 /**
- * A field access of a field of `this`. The access has no qualifier because
+ * A field access of a field of `this` which has no qualifier because
  * the use of `this` is implicit. For example, `field` is equivalent to
  * `this->field` if `field` is a member of `this`.
  *
@@ -250,7 +312,15 @@ class PointerToFieldLiteral extends ImplicitThisFieldAccess {
 }
 
 /**
- * A C/C++ function access expression.
+ * A C/C++ function access expression. For example the access to
+ * `myFunctionTarget` in `myFunction` in the following code:
+ * ```
+ * int myFunctionTarget(int);
+ *
+ * void myFunction() {
+ *   int (*myFunctionPointer)(int) = &myTarget;
+ * }
+ * ```
  */
 class FunctionAccess extends Access, @routineexpr {
   FunctionAccess() { not iscall(underlyingElement(this), _) }
@@ -269,7 +339,7 @@ class FunctionAccess extends Access, @routineexpr {
 }
 
 /**
- * An access to a parameter of a function signature for the purposes of a decltype.
+ * An access to a parameter of a function signature for the purposes of a `decltype`.
  *
  * For example, given the following code:
  * ```
@@ -279,7 +349,7 @@ class FunctionAccess extends Access, @routineexpr {
  *   }
  * ```
  * The return type of the function is a decltype, the expression of which contains
- * an add expression, which in turn has two ParamAccessForType children.
+ * an add expression, which in turn has two `ParamAccessForType` children.
  */
 class ParamAccessForType extends Expr, @param_ref {
   override string toString() { result = "param access" }
@@ -287,7 +357,22 @@ class ParamAccessForType extends Expr, @param_ref {
 
 /**
  * An access to a type.  This occurs in certain contexts where a built-in
- * works on types directly rather than variables, expressions etc.
+ * works on types directly rather than variables, expressions etc.  For
+ * example the reference to `MyClass` in `__is_pod` in the following code:
+ * ```
+ * class MyClass {
+ *   ...
+ * };
+ *
+ * void myFunction() {
+ *   if (__is_pod(MyClass))
+ *   {
+ *     ...
+ *   } else {
+ *     ...
+ *   }
+ * }
+ * ```
  */
 class TypeName extends Expr, @type_operand {
   override string getCanonicalQLClass() { result = "TypeName" }
@@ -296,9 +381,17 @@ class TypeName extends Expr, @type_operand {
 }
 
 /**
- * A C/C++ array access expression.
+ * A C/C++ array access expression. For example, the access to `as` in
+ * `myFunction` in the following code:
+ * ```
+ * int as[10];
  *
- * For calls to operator[], which look syntactically identical, see OverloadedArrayExpr.
+ * void myFunction() {
+ *   as[0]++;
+ * }
+ * ```
+ * For calls to `operator[]`, which look syntactically identical, see
+ * `OverloadedArrayExpr`.
  */
 class ArrayExpr extends Expr, @subscriptexpr {
   override string getCanonicalQLClass() { result = "ArrayExpr" }
@@ -306,14 +399,14 @@ class ArrayExpr extends Expr, @subscriptexpr {
   /**
    * Gets the array or pointer expression being subscripted.
    *
-   * This is arr in both arr[0] and 0[arr].
+   * This is `arr` in both `arr[0]` and `0[arr]`.
    */
   Expr getArrayBase() { result = this.getChild(0) }
 
   /**
    * Gets the expression giving the index into the array.
    *
-   * This is 0 in both arr[0] and 0[arr].
+   * This is `0` in both `arr[0]` and `0[arr]`.
    */
   Expr getArrayOffset() { result = this.getChild(1) }