Merge pull request #2309 from geoffw0/cpp418

CPP: QLDoc enhancements

Author: jbj

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

@@ -2,12 +2,11 @@ import semmle.code.cpp.Type
 private import semmle.code.cpp.internal.ResolveClass
 
 /**
- * A C/C++ typedef type. See 4.9.1.
- *
- * Represents either of the following typedef styles:
- *
- *   * CTypedefType: typedef <type> <name>;
- *   * UsingAliasTypedefType: using <name> = <type>;
+ * A C/C++ typedef type. See 4.9.1.  For example the types declared on each line of the following code:
+ * ```
+ * typedef int my_int;
+ * using my_int2 = int;
+ * ```
  */
 class TypedefType extends UserType {
   TypedefType() {
@@ -48,7 +47,10 @@ class TypedefType extends UserType {
 }
 
 /**
- * A traditional C/C++ typedef type. See 4.9.1.
+ * A traditional C/C++ typedef type. See 4.9.1.  For example the type declared in the following code:
+ * ```
+ * typedef int my_int;
+ * ```
  */
 class CTypedefType extends TypedefType {
   CTypedefType() { usertypes(underlyingElement(this), _, 5) }
@@ -61,7 +63,10 @@ class CTypedefType extends TypedefType {
 }
 
 /**
- * A using alias C++ typedef type.
+ * A using alias C++ typedef type.  For example the type declared in the following code:
+ * ```
+ * using my_int2 = int;
+ * ```
  */
 class UsingAliasTypedefType extends TypedefType {
   UsingAliasTypedefType() { usertypes(underlyingElement(this), _, 14) }
@@ -74,7 +79,11 @@ class UsingAliasTypedefType extends TypedefType {
 }
 
 /**
- * A C++ typedef type that is directly enclosed by a function.
+ * A C++ `typedef` type that is directly enclosed by a function.  For example the type declared inside the function `foo` in
+ * the following code:
+ * ```
+ * int foo(void) { typedef int local; }
+ * ```
  */
 class LocalTypedefType extends TypedefType {
   LocalTypedefType() { isLocal() }
@@ -83,7 +92,11 @@ class LocalTypedefType extends TypedefType {
 }
 
 /**
- * A C++ typedef type that is directly enclosed by a class, struct or union.
+ * A C++ `typedef` type that is directly enclosed by a `class`, `struct` or `union`.  For example the type declared inside
+ * the class `C` in the following code:
+ * ```
+ * class C { typedef int nested; };
+ * ```
  */
 class NestedTypedefType extends TypedefType {
   NestedTypedefType() { this.isMember() }

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

@@ -5,8 +5,14 @@ import semmle.code.cpp.Function
 private import semmle.code.cpp.internal.ResolveClass
 
 /**
- * A C/C++ user-defined type. Examples include `Class`, `Struct`, `Union`,
- * `Enum`, and `TypedefType`.
+ * A C/C++ user-defined type. Examples include `class`, `struct`, `union`,
+ * `enum` and `typedef` types.
+ * ```
+ * enum e1 { val1, val2 } b;
+ * enum class e2: short { val3, val4 } c;
+ * typedef int my_int;
+ * class C { int a, b; };
+ * ```
  */
 class UserType extends Type, Declaration, NameQualifyingElement, AccessHolder, @usertype {
   /**
@@ -88,6 +94,10 @@ class UserType extends Type, Declaration, NameQualifyingElement, AccessHolder, @
 
 /**
  * A particular definition or forward declaration of a C/C++ user-defined type.
+ * ```
+ * class C;
+ * typedef int ti;
+ * ```
  */
 class TypeDeclarationEntry extends DeclarationEntry, @type_decl {
   override UserType getDeclaration() { result = getType() }

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

@@ -44,7 +44,7 @@ predicate memberMayBeVarSize(Class c, MemberVariable v) {
       aoe.getAddressable() = v
     )
     or
-    exists(BuiltInOperationOffsetOf oo |
+    exists(BuiltInOperationBuiltInOffsetOf oo |
       // `offsetof(c, v)` using a builtin
       oo.getAChild().(VariableAccess).getTarget() = v
     )

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

@@ -132,7 +132,7 @@ private predicate excludeNodeAndNodesBelow(Expr e) {
  * control flow in them.
  */
 private predicate excludeNodesStrictlyBelow(Node n) {
-  n instanceof BuiltInOperationOffsetOf
+  n instanceof BuiltInOperationBuiltInOffsetOf
   or
   n instanceof BuiltInIntAddr
   or