[CPP-418] Add QLDoc entries for typedef types, user types, bitwise operations and built-in operations.

zlaski-semmle · geoffw0 · commit b0a93481cb2b · 2019-11-12T17:33:07.000Z
diff --git a/cpp/ql/src/semmle/code/cpp/Type.qll b/cpp/ql/src/semmle/code/cpp/Type.qll
@@ -362,7 +362,7 @@ private predicate isIntegralType(@builtintype type, int kind) {
 }
 
 /**
- * A C/C++ integral or enum type.
+ * A C/C++ integral or `enum` type.
  *
  * The definition of "integral type" in the C++ Standard excludes `enum` types,
  * but because an `enum` type holds a value of its underlying integral type,
@@ -569,7 +569,7 @@ class PlainCharType extends CharType {
 
 /**
  * The C/C++ `unsigned char` type (which is distinct from plain `char`
- * even when `char` is unsigned by default).
+ * even when `char` is `unsigned` by default).
  * ```
  * unsigned char e, f;
  * ```
@@ -582,7 +582,7 @@ class UnsignedCharType extends CharType {
 
 /**
  * The C/C++ `signed char` type (which is distinct from plain `char`
- * even when `char` is signed by default).
+ * even when `char` is `signed` by default).
  * ```
  * signed char c, d;
  * ```
@@ -928,17 +928,17 @@ class Decltype extends Type, @decltype {
    */
   Type getBaseType() { decltypes(underlyingElement(this), _, unresolveElement(result), _) }
 
-  override string getCanonicalQLClass() { result = "Decltype" }
-
   /**
    * Whether an extra pair of parentheses around the expression would change the semantics of this decltype.
    *
    * The following example shows the effect of an extra pair of parentheses:
-   *   struct A { double x; };
-   *   const A* a = new A();
-   *   decltype( a->x ); // type is double
-   *   decltype((a->x)); // type is const double&amp;
-   * Consult the C++11 standard for more details.
+   * ```
+   * struct A { double x; };
+   * const A* a = new A();
+   * decltype( a->x ); // type is double
+   * decltype((a->x)); // type is const double&amp;
+   * ```
+   * Please consult the C++11 standard for more details.
    */
   predicate parenthesesWouldChangeMeaning() { decltypes(underlyingElement(this), _, _, true) }
 
@@ -1007,7 +1007,7 @@ class PointerType extends DerivedType {
 /**
  * A C++ reference type. See 4.9.1.
  *
- * For C++11 code bases, this includes both _lvalue_ references (&amp;) and _rvalue_ references (&amp;&amp;).
+ * For C++11 code bases, this includes both _lvalue_ references (`&`) and _rvalue_ references (`&&`).
  * To distinguish between them, use the LValueReferenceType and RValueReferenceType classes.
  */
 class ReferenceType extends DerivedType {
@@ -1033,7 +1033,7 @@ class ReferenceType extends DerivedType {
 }
 
 /**
- * A C++11 lvalue reference type (e.g. `int&amp;`).
+ * A C++11 lvalue reference type (e.g. `int &`).
  * ```
  * int a;
  * int& b = a;
@@ -1046,8 +1046,8 @@ class LValueReferenceType extends ReferenceType {
 }
 
 /**
- * A C++11 rvalue reference type (e.g. `int&amp;&amp;`).  It is used to
- * implement "move" semantics for object construction and assignments.
+ * A C++11 rvalue reference type (e.g., `int &&`).  It is used to
+ * implement "move" semantics for object construction and assignment.
  * ```
  * class C {
  *   E e;
@@ -1251,7 +1251,7 @@ class FunctionReferenceType extends FunctionPointerIshType {
 }
 
 /**
- * A block type, for example int(^)(char, float).
+ * A block type, for example, `int(^)(char, float)`.
  *
  * Block types (along with blocks themselves) are a language extension
  * supported by Clang, and by Apple's branch of GCC.
diff --git a/cpp/ql/src/semmle/code/cpp/TypedefType.qll b/cpp/ql/src/semmle/code/cpp/TypedefType.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() }
diff --git a/cpp/ql/src/semmle/code/cpp/UserType.qll b/cpp/ql/src/semmle/code/cpp/UserType.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,11 @@ 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;
+ * extern void foo(int);
+ * ```
  */
 class TypeDeclarationEntry extends DeclarationEntry, @type_decl {
   override UserType getDeclaration() { result = getType() }
diff --git a/cpp/ql/src/semmle/code/cpp/exprs/BitwiseOperation.qll b/cpp/ql/src/semmle/code/cpp/exprs/BitwiseOperation.qll
@@ -7,6 +7,9 @@ abstract class UnaryBitwiseOperation extends UnaryOperation { }
 
 /**
  * A C/C++ complement expression.
+ * ```
+ * unsigned c = ~a;
+ * ```
  */
 class ComplementExpr extends UnaryBitwiseOperation, @complementexpr {
   override string getOperator() { result = "~" }
@@ -23,6 +26,9 @@ abstract class BinaryBitwiseOperation extends BinaryOperation { }
 
 /**
  * A C/C++ left shift expression.
+ * ```
+ * unsigned c = a << b;
+ * ```
  */
 class LShiftExpr extends BinaryBitwiseOperation, @lshiftexpr {
   override string getOperator() { result = "<<" }
@@ -34,6 +40,9 @@ class LShiftExpr extends BinaryBitwiseOperation, @lshiftexpr {
 
 /**
  * A C/C++ right shift expression.
+ * ```
+ * unsigned c = a >> b;
+ * ```
  */
 class RShiftExpr extends BinaryBitwiseOperation, @rshiftexpr {
   override string getOperator() { result = ">>" }
@@ -44,7 +53,10 @@ class RShiftExpr extends BinaryBitwiseOperation, @rshiftexpr {
 }
 
 /**
- * A C/C++ bitwise and expression.
+ * A C/C++ bitwise AND expression.
+ * ```
+ * unsigned c = a & b;
+ * ```
  */
 class BitwiseAndExpr extends BinaryBitwiseOperation, @andexpr {
   override string getOperator() { result = "&" }
@@ -55,7 +67,10 @@ class BitwiseAndExpr extends BinaryBitwiseOperation, @andexpr {
 }
 
 /**
- * A C/C++ bitwise or expression.
+ * A C/C++ bitwise OR expression.
+ * ```
+ * unsigned c = a | b;
+ * ```
  */
 class BitwiseOrExpr extends BinaryBitwiseOperation, @orexpr {
   override string getOperator() { result = "|" }
@@ -66,7 +81,10 @@ class BitwiseOrExpr extends BinaryBitwiseOperation, @orexpr {
 }
 
 /**
- * A C/C++ bitwise xor expression.
+ * A C/C++ bitwise XOR expression.
+ * ```
+ * unsigned c = a ^ b;
+ * ```
  */
 class BitwiseXorExpr extends BinaryBitwiseOperation, @xorexpr {
   override string getOperator() { result = "^" }
diff --git a/cpp/ql/src/semmle/code/cpp/exprs/BuiltInOperations.qll b/cpp/ql/src/semmle/code/cpp/exprs/BuiltInOperations.qll
