Merge pull request #5097 from geoffw0/qldoceg11

C++: QLDoc Improvements

Author: jbj

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

@@ -270,7 +270,12 @@ private predicate isFromUninstantiatedTemplateRec(Element e, Element template) {
 }
 
 /**
- * A C++11 `static_assert` or C11 `_Static_assert` construct.
+ * A C++11 `static_assert` or C11 `_Static_assert` construct. For example each
+ * line in the following example contains a static assert:
+ * ```
+ * static_assert(sizeof(MyStruct) <= 4096);
+ * static_assert(sizeof(MyStruct) <= 4096, "MyStruct is too big!");
+ * ```
  */
 class StaticAssert extends Locatable, @static_assert {
   override string toString() { result = "static_assert(..., \"" + getMessage() + "\")" }

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

@@ -7,8 +7,21 @@ import semmle.code.cpp.Type
 import semmle.code.cpp.metrics.MetricNamespace
 
 /**
- * A C++ namespace.
+ * A C++ namespace. For example the (single) namespace `A` in the following
+ * code:
+ * ```
+ * namespace A
+ * {
+ *   // ...
+ * }
  *
+ * // ...
+ *
+ * namespace A
+ * {
+ *   // ...
+ * }
+ * ```
  * Note that namespaces are somewhat nebulous entities, as they do not in
  * general have a single well-defined location in the source code. The
  * related notion of a `NamespaceDeclarationEntry` is rather more concrete,
@@ -96,10 +109,22 @@ class Namespace extends NameQualifyingElement, @namespace {
 }
 
 /**
- * A declaration of (part of) a C++ namespace.
+ * A declaration of (part of) a C++ namespace. This corresponds to a single
+ * `namespace N { ... }` occurrence in the source code. For example the two
+ * mentions of `A` in the following code:
+ * ```
+ * namespace A
+ * {
+ *   // ...
+ * }
+ *
+ * // ...
  *
- * This corresponds to a single `namespace N { ... }` occurrence in the
- * source code.
+ * namespace A
+ * {
+ *   // ...
+ * }
+ * ```
  */
 class NamespaceDeclarationEntry extends Locatable, @namespace_decl {
   /**
@@ -143,8 +168,9 @@ class UsingEntry extends Locatable, @using {
 
 /**
  * A C++ `using` declaration. For example:
- *
- *   `using std::string;`
+ * ```
+ * using std::string;
+ * ```
  */
 class UsingDeclarationEntry extends UsingEntry {
   UsingDeclarationEntry() {
@@ -162,8 +188,9 @@ class UsingDeclarationEntry extends UsingEntry {
 
 /**
  * A C++ `using` directive. For example:
- *
- *   `using namespace std;`
+ * ```
+ * using namespace std;
+ * ```
  */
 class UsingDirectiveEntry extends UsingEntry {
   UsingDirectiveEntry() {

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

@@ -2,9 +2,14 @@ import semmle.code.cpp.Location
 import semmle.code.cpp.Element
 
 /**
- * A C/C++ preprocessor directive.
- *
- * For example: `#ifdef`, `#line`, or `#pragma`.
+ * A C/C++ preprocessor directive. For example each of the following lines of
+ * code contains a `PreprocessorDirective`:
+ * ```
+ * #pragma once
+ * #ifdef MYDEFINE
+ * #include "myfile.h"
+ * #line 1 "source.c"
+ * ```
  */
 class PreprocessorDirective extends Locatable, @preprocdirect {
   override string toString() { result = "Preprocessor directive" }
@@ -98,9 +103,9 @@ class PreprocessorBranchDirective extends PreprocessorDirective, TPreprocessorBr
  * A C/C++ preprocessor branching directive: `#if`, `#ifdef`, `#ifndef`, or
  * `#elif`.
  *
- * A branching directive can have its condition evaluated at compile-time,
- * and as a result, the preprocessor will either take the branch, or not
- * take the branch.
+ * A branching directive has a condition and that condition may be evaluated
+ * at compile-time.  As a result, the preprocessor will either take the
+ * branch, or not take the branch.
  *
  * However, there are also situations in which a branch's condition isn't
  * evaluated.  The obvious case of this is when the directive is contained
@@ -136,8 +141,13 @@ class PreprocessorBranch extends PreprocessorBranchDirective, @ppd_branch {
 }
 
 /**
- * A C/C++ preprocessor `#if` directive.
- *
+ * A C/C++ preprocessor `#if` directive. For example there is a
+ * `PreprocessorIf` on the first line of the following code:
+ * ```
+ * #if defined(MYDEFINE)
+ * // ...
+ * #endif
+ * ```
  * For the related notion of a directive which causes branching (which
  * includes `#if`, plus also `#ifdef`, `#ifndef`, and `#elif`), see
  * `PreprocessorBranch`.
@@ -147,8 +157,13 @@ class PreprocessorIf extends PreprocessorBranch, @ppd_if {
 }
 
 /**
- * A C/C++ preprocessor `#ifdef` directive.
- *
+ * A C/C++ preprocessor `#ifdef` directive. For example there is a
+ * `PreprocessorIfdef` on the first line of the following code:
+ * ```
+ * #ifdef MYDEFINE
+ * // ...
+ * #endif
+ * ```
  * The syntax `#ifdef X` is shorthand for `#if defined(X)`.
  */
 class PreprocessorIfdef extends PreprocessorBranch, @ppd_ifdef {
@@ -158,51 +173,94 @@ class PreprocessorIfdef extends PreprocessorBranch, @ppd_ifdef {
 }
 
 /**
- * A C/C++ preprocessor `#ifndef` directive.
- *
+ * A C/C++ preprocessor `#ifndef` directive. For example there is a
+ * `PreprocessorIfndef` on the first line of the following code:
+ * ```
+ * #ifndef MYDEFINE
+ * // ...
+ * #endif
+ * ```
  * The syntax `#ifndef X` is shorthand for `#if !defined(X)`.
  */
 class PreprocessorIfndef extends PreprocessorBranch, @ppd_ifndef {
   override string toString() { result = "#ifndef " + this.getHead() }
 }
 
 /**
- * A C/C++ preprocessor `#else` directive.
+ * A C/C++ preprocessor `#else` directive. For example there is a
+ * `PreprocessorElse` on the fifth line of the following code:
+ * ```
+ * #ifdef MYDEFINE1
+ * // ...
+ * #elif MYDEFINE2
+ * // ...
+ * #else
+ * // ...
+ * #endif
+ * ```
  */
 class PreprocessorElse extends PreprocessorBranchDirective, @ppd_else {
   override string toString() { result = "#else" }
 }
 
 /**
- * A C/C++ preprocessor `#elif` directive.
+ * A C/C++ preprocessor `#elif` directive. For example there is a
+ * `PreprocessorElif` on the third line of the following code:
+ * ```
+ * #ifdef MYDEFINE1
+ * // ...
+ * #elif MYDEFINE2
+ * // ...
+ * #else
+ * // ...
+ * #endif
+ * ```
  */
 class PreprocessorElif extends PreprocessorBranch, @ppd_elif {
   override string toString() { result = "#elif " + this.getHead() }
 }
 
 /**
- * A C/C++ preprocessor `#endif` directive.
+ * A C/C++ preprocessor `#endif` directive. For example there is a
+ * `PreprocessorEndif` on the third line of the following code:
+ * ```
+ * #ifdef MYDEFINE
+ * // ...
+ * #endif
+ * ```
  */
 class PreprocessorEndif extends PreprocessorBranchDirective, @ppd_endif {
   override string toString() { result = "#endif" }
 }
 
 /**
- * A C/C++ preprocessor `#warning` directive.
+ * A C/C++ preprocessor `#warning` directive. For example:
+ * ```
+ * #warning "This configuration is not supported."
+ * ```
  */
 class PreprocessorWarning extends PreprocessorDirective, @ppd_warning {
   override string toString() { result = "#warning " + this.getHead() }
 }
 
 /**
- * A C/C++ preprocessor `#error` directive.
+ * A C/C++ preprocessor `#error` directive. For example:
+ * ```
+ * #error "This configuration is not implemented."
+ * ```
  */
 class PreprocessorError extends PreprocessorDirective, @ppd_error {
   override string toString() { result = "#error " + this.getHead() }
 }
 
 /**
- * A C/C++ preprocessor `#undef` directive.
+ * A C/C++ preprocessor `#undef` directive. For example there is a
+ * `PreprocessorUndef` on the second line of the following code:
+ * ```
+ * #ifdef MYMACRO
+ * #undef MYMACRO
+ * #endif
+ * ```
  */
 class PreprocessorUndef extends PreprocessorDirective, @ppd_undef {
   override string toString() { result = "#undef " + this.getHead() }
@@ -214,7 +272,10 @@ class PreprocessorUndef extends PreprocessorDirective, @ppd_undef {
 }
 
 /**
- * A C/C++ preprocessor `#pragma` directive.
+ * A C/C++ preprocessor `#pragma` directive. For example:
+ * ```
+ * #pragma once
+ * ```
  */
 class PreprocessorPragma extends PreprocessorDirective, @ppd_pragma {
   override string toString() {
@@ -223,7 +284,10 @@ class PreprocessorPragma extends PreprocessorDirective, @ppd_pragma {
 }
 
 /**
- * A C/C++ preprocessor `#line` directive.
+ * A C/C++ preprocessor `#line` directive. For example:
+ * ```
+ * #line 1 "source.c"
+ * ```
  */
 class PreprocessorLine extends PreprocessorDirective, @ppd_line {
   override string toString() { result = "#line " + this.getHead() }

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

@@ -171,8 +171,11 @@ class StdAttribute extends Attribute, @stdattribute {
 }
 
 /**
- * An attribute introduced by Microsoft's `__declspec(name)` syntax, for
- * example: `__declspec(dllimport)`.
+ * An attribute introduced by Microsoft's `__declspec(name)` syntax.  For
+ * example the attribute on the following declaration:
+ * ```
+ * __declspec(dllimport) void myFunction();
+ * ```
  */
 class Declspec extends Attribute, @declspec { }
 
@@ -186,8 +189,13 @@ class MicrosoftAttribute extends Attribute, @msattribute {
 }
 
 /**
- * A C++11 `alignas` construct.
- *
+ * A C++11 `alignas` construct. For example the attribute in the following
+ * code:
+ * ```
+ * struct alignas(16) MyStruct {
+ *   int x;
+ * };
+ * ```
  * Though it doesn't use the attribute syntax, `alignas(...)` is presented
  * as an `Attribute` for consistency with the `[[align(...)]]` attribute.
  */
@@ -197,7 +205,11 @@ class AlignAs extends Attribute, @alignas {
 
 /**
  * A GNU `format` attribute of the form `__attribute__((format(archetype, format-index, first-arg)))`
- * that declares a function to accept a `printf` style format string.
+ * that declares a function to accept a `printf` style format string.  For example the attribute
+ * on the following declaration:
+ * ```
+ * int myPrintf(const char *format, ...) __attribute__((format(printf, 1, 2)));
+ * ```
  */
 class FormatAttribute extends GnuAttribute {
   FormatAttribute() { getName() = "format" }
@@ -242,7 +254,11 @@ class FormatAttribute extends GnuAttribute {
 }
 
 /**
- * An argument to an `Attribute`.
+ * An argument to an `Attribute`. For example the argument "dllimport" on the
+ * attribute in the following code:
+ * ```
+ * __declspec(dllimport) void myFunction();
+ * ```
  */
 class AttributeArgument extends Element, @attribute_arg {
   /**