Merge pull request #1770 from geoffw0/qldoceg7

CPP: Add syntax examples to QLDoc in various files

Author: zlaski-semmle

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

@@ -2,7 +2,11 @@ import semmle.code.cpp.Location
 import semmle.code.cpp.Element
 
 /**
- * A C/C++ comment.
+ * A C/C++ comment. For example the comment in the following code:
+ * ```
+ * // C++ style single-line comment
+ * ```
+ * or a C style comment (which starts with `/*`).
  */
 class Comment extends Locatable, @comment {
   override string toString() { result = this.getContents() }
@@ -21,7 +25,10 @@ class CStyleComment extends Comment {
 }
 
 /**
- * A CPP style comment (one which starts with `//`).
+ * A CPP style comment. For example the comment in the following code:
+ * ```
+ * // C++ style single-line comment
+ * ```
  */
 class CppStyleComment extends Comment {
   CppStyleComment() {

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

@@ -3,7 +3,18 @@ import semmle.code.cpp.Enum
 import semmle.code.cpp.exprs.Access
 
 /**
- * A C structure member or C++ non-static member variable.
+ * A C structure member or C++ non-static member variable. For example the
+ * member variable `m` in the following code (but not `s`):
+ * ```
+ * class MyClass {
+ * public:
+ *   int m;
+ *   static int s;
+ * };
+ * ```
+ *
+ * This does not include static member variables in C++. To include static member
+ * variables, use `MemberVariable` instead of `Field`.
  */
 class Field extends MemberVariable {
 
@@ -33,12 +44,13 @@ class Field extends MemberVariable {
   /**
    * Holds if the field can be initialized as part of an initializer list. For
    * example, in:
-   *
+   * ```
    * struct S {
    *   unsigned int a : 5;
    *   unsigned int : 5;
    *   unsigned int b : 5; 
    * };
+   * ```
    *
    * Fields `a` and `b` are initializable, but the unnamed bitfield is not.
    */
@@ -65,9 +77,13 @@ class Field extends MemberVariable {
 }
 
 /**
- * A C structure member or C++ member variable declared with an explicit size in bits.
- *
- * Syntactically, this looks like `int x : 3` in `struct S { int x : 3; };`.
+ * A C structure member or C++ member variable declared with an explicit size
+ * in bits. For example the member variable `x` in the following code:
+ * ```
+ * struct MyStruct {
+ *   int x : 3;
+ * };
+ * ```
  */
 class BitField extends Field {
   BitField() { bitfield(underlyingElement(this),_,_) }

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

@@ -2,16 +2,17 @@ import semmle.code.cpp.Declaration
 private import semmle.code.cpp.internal.ResolveClass
 
 /**
- * A C++ friend declaration [N4140 11.3].
- * For example:
+ * A C++ friend declaration [N4140 11.3]. For example the two friend
+ * declarations in class `A` of the following code:
+ * ```
+ * class A {
+ *   friend void f(int);
+ *   friend class X;
+ * };
  *
- *   class A {
- *     friend void f(int);
- *     friend class X;
- *   };
- *
- *   void f(int x) { ... }
- *   class X { ... };
+ * void f(int x) { ... }
+ * class X { ... };
+ * ```
  */
 class FriendDecl extends Declaration, @frienddecl {
   /**

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

@@ -2,7 +2,14 @@ import semmle.code.cpp.Preprocessor
 
 /**
  * A C/C++ `#include`, `#include_next`, or `#import` preprocessor
- * directive.
+ * directive. The following example contains four different `Include`
+ * directives:
+ * ```
+ * #include "header.h"
+ * #include <string>
+ * #include_next <header2.h>
+ * #import <header3.h>
+ * ```
  */
 class Include extends PreprocessorDirective, @ppd_include {
   override string toString() { result = "#include " + this.getIncludeText() }
@@ -37,7 +44,10 @@ class Include extends PreprocessorDirective, @ppd_include {
 
 /**
  * A `#include_next` preprocessor directive (a non-standard extension to
- * C/C++).
+ * C/C++). For example the following code contains one `IncludeNext` directive:
+ * ```
+ * #include_next <header2.h>
+ * ```
  */
 class IncludeNext extends Include, @ppd_include_next {
   override string toString() {
@@ -47,7 +57,11 @@ class IncludeNext extends Include, @ppd_include_next {
 
 /**
  * A `#import` preprocessor directive (used heavily in Objective C, and
- * supported by GCC as an extension in C).
+ * supported by GCC as an extension in C). For example the following code
+ * contains one `Import` directive:
+ * ```
+ * #import <header3.h>
+ * ```
  */
 class Import extends Include, @ppd_objc_import {
   override string toString() {

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

@@ -1,7 +1,10 @@
 import cpp
 
 /**
- * A macro.
+ * A macro. For example, the macro `MYMACRO` in the following code:
+ * ```
+ * #define MYMACRO 1
+ * ```
  */
 class Macro extends PreprocessorDirective, @ppd_define {
 

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

@@ -2,7 +2,13 @@ import semmle.code.cpp.exprs.Expr
 import semmle.code.cpp.Class
 
 /**
- * A C++11 lambda expression, such as `[&, =y](int x) mutable -> double {return z = (y += x);}`.
+ * A C++11 lambda expression, for example the expression initializing `a` in
+ * the following code:
+ * ```
+ * auto a = [x, y](int z) -> int {
+ *   return x + y + z;
+ * };
+ * ```
  *
  * The type given by `getType()` will be an instance of `Closure`.
  */
@@ -71,6 +77,12 @@ class LambdaExpression extends Expr, @lambdaexpr {
 
 /**
  * A class written by the compiler to be the type of a C++11 lambda expression.
+ * For example the variable `a` in the following code has a closure type:
+ * ```
+ * auto a = [x, y](int z) -> int {
+ *   return x + y + z;
+ * };
+ * ```
  */
 class Closure extends Class {
   Closure() {
@@ -96,7 +108,13 @@ class Closure extends Class {
 }
 
 /**
- * Information about a value captured as part of a lambda expression.
+ * Information about a value captured as part of a lambda expression.  For
+ * example in the following code, information about `x` and `y` is captured:
+ * ```
+ * auto a = [x, y](int z) -> int {
+ *   return x + y + z;
+ * };
+ * ```
  */
 class LambdaCapture extends Locatable, @lambdacapture {
   override string toString() {