Merge pull request #1771 from geoffw0/qldoceg8

CPP: Add syntax examples to QLDoc in NameQualifiers.qll

Author: zlaski-semmle

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

@@ -2,11 +2,16 @@ import semmle.code.cpp.Type
 private import semmle.code.cpp.internal.ResolveClass
 
 /**
- * A C/C++ enum [N4140 7.2]. For example, the type `MyEnum` in:
+ * A C/C++ enum [N4140 7.2]. For example, the types `MyEnum` and
+ * `MyScopedEnum` in:
  * ```
  * enum MyEnum {
  *   MyEnumConstant
  * };
+ *
+ * enum class MyScopedEnum {
+ *   MyScopedEnumConstant
+ * };
  * ```
  * This includes C++ scoped enums, see the `ScopedEnum` QL class.
  */

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

@@ -1,7 +1,18 @@
 import cpp
 
 /**
- * A C++ name qualifier, for example `N::`.
+ * A C++ name qualifier, for example `N::` in the following code:
+ * ```
+ * namespace N {
+ *   int f() {
+ *     ...
+ *   }
+ * }
+ *
+ * int g() {
+ *   return N::f();
+ * }
+ * ```
  */
 class NameQualifier extends NameQualifiableElement, @namequalifier {
   /**
@@ -61,10 +72,21 @@ class NameQualifier extends NameQualifiableElement, @namequalifier {
 
 /**
  * A C++ element that can be qualified with a name. This is in practice
- * either an expression or a name qualifier. For instance, in
- * `N1::N2::f()`, there are two name-qualifiable elements: the expression
- * `f()` and the name qualifier `N2::`. The former is qualified by `N2` and
- * the latter is qualified by `N1`.
+ * either an expression or a name qualifier. For example, there are two
+ * name-qualifiable elements in the following code, the expression `f()`
+ * (which is qualified by `N::`), and the qualifier `N::` (which is not
+ * itself qualified in this example):
+ * ```
+ * namespace N {
+ *   int f() {
+ *     ...
+ *   }
+ * }
+ *
+ * int g() {
+ *   return N::f();
+ * }
+ * ```
  */
 class NameQualifiableElement extends Element, @namequalifiableelement {
   /**
@@ -99,8 +121,19 @@ class NameQualifiableElement extends Element, @namequalifiableelement {
 }
 
 /**
- * A C++ element that can qualify a name. For example, `N` in `N::f()`.  A
- * name-qualifying element is either a namespace or a user-defined type.
+ * A C++ element that can qualify a name. For example, the namespaces `A` and
+ * `A::B` and the class `A::C` in the following code:
+ * ```
+ * namespace A {
+ *   namespace B {
+ *     ...
+ *   }
+ * 
+ *   class C {
+ *     ...
+ *   };
+ * }
+ * ```
  */
 class NameQualifyingElement extends Element, @namequalifyingelement {
   /**

cpp/ql/test/library-tests/namespaces/namespaces/namequalifiable.expected

@@ -0,0 +1,11 @@
+| file://:0:0:0:0 | (global namespace) | NameQualifyingElement |
+| file://:0:0:0:0 | B | NameQualifyingElement |
+| namespaces.cpp:1:11:1:11 | A | NameQualifyingElement |
+| namespaces.cpp:9:11:9:11 | C | NameQualifyingElement |
+| namespaces.cpp:11:13:11:13 | C::D | NameQualifyingElement |
+| namespaces.cpp:13:30:13:30 | 0 | NameQualifiableElement |
+| namespaces.cpp:15:12:15:12 | E | NameQualifyingElement |
+| namespaces.cpp:32:11:32:13 | C:: | NameQualifiableElement |
+| namespaces.cpp:32:11:32:17 | call to f | NameQualifiableElement |
+| namespaces.cpp:32:14:32:16 | D:: | NameQualifiableElement |
+| namespaces.cpp:36:11:36:13 | std | NameQualifyingElement |

cpp/ql/test/library-tests/namespaces/namespaces/namequalifiable.ql

@@ -0,0 +1,15 @@
+import cpp
+
+string describe(Element e) {
+	(
+		e instanceof NameQualifiableElement and
+		result = "NameQualifiableElement"
+	) or (
+		e instanceof NameQualifyingElement and
+		result = "NameQualifyingElement"
+	)
+}
+
+from Element e
+where e.getFile().fromSource() or e instanceof Namespace
+select e, strictconcat(describe(e), ", ")