Merge pull request #1705 from geoffw0/qldoceg2

CPP: Add syntax examples to QLDoc in Enum.qll.

Author: jbj

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

@@ -2,7 +2,13 @@ import semmle.code.cpp.Type
 private import semmle.code.cpp.internal.ResolveClass
 
 /**
- * A C/C++ enum [N4140 7.2].
+ * A C/C++ enum [N4140 7.2]. For example, the type `MyEnum` in:
+ * ```
+ * enum MyEnum {
+ *   MyEnumConstant
+ * };
+ * ```
+ * This includes C++ scoped enums, see the `ScopedEnum` QL class.
  */
 class Enum extends UserType, IntegralOrEnumType {
   /** Gets an enumerator of this enumeration. */
@@ -46,7 +52,15 @@ class Enum extends UserType, IntegralOrEnumType {
 }
 
 /**
- * A C++ enum that is directly enclosed by a function.
+ * A C/C++ enum that is directly enclosed by a function. For example, the type
+ * `MyLocalEnum` in:
+ * ```
+ * void myFunction() {
+ *   enum MyLocalEnum {
+ *     MyLocalEnumConstant
+ *   };
+ * }
+ * ```
  */
 class LocalEnum extends Enum {
   LocalEnum() {
@@ -57,7 +71,16 @@ class LocalEnum extends Enum {
 }
 
 /**
- * A C++ enum that is declared within a class.
+ * A C/C++ enum that is declared within a class/struct. For example, the type
+ * `MyNestedEnum` in:
+ * ```
+ * class MyClass {
+ * public:
+ *   enum MyNestedEnum {
+ *     MyNestedEnumConstant
+ *   };
+ * };
+ * ```
  */
 class NestedEnum extends Enum {
 
@@ -79,9 +102,14 @@ class NestedEnum extends Enum {
 }
 
 /**
- * A C++ scoped enum.
- *
- * For example, `enum class Color { red, blue }`.
+ * A C++ scoped enum, that is, an enum whose constants must be qualified with
+ * the name of the enum. For example, the type `Color` in:
+ * ```
+ * enum class Color {
+ *   red,
+ *   blue
+ * }
+ * ```
  */
 class ScopedEnum extends Enum {
   ScopedEnum() {
@@ -92,11 +120,16 @@ class ScopedEnum extends Enum {
 }
 
 /**
- * A C/C++ enumerator [N4140 7.2].
- *
- * For example: `green` in `enum { red, green, blue }`.
+ * A C/C++ enumerator [N4140 7.2], also known as an enumeration constant.
  *
- * Enumerators are also knowns as enumeration constants.
+ * For example the enumeration constant `green` in:
+ * ```
+ * enum {
+ *   red,
+ *   green,
+ *   blue
+ * }
+ * ```
  */
 class EnumConstant extends Declaration, @enumconstant {
   /**

cpp/ql/test/library-tests/enums/enums/Enums1.expected

@@ -11,6 +11,8 @@
 | enums.cpp:5:13:5:13 | b | b | 1 | Flag | 1 | 1 | 1 |
 | enums.cpp:5:22:5:22 | c | c | 1 | Flag | 1 | 1 | 1 |
 | enums.cpp:5:31:5:31 | d | d | 1 | Flag | 1 | 1 | 1 |
+| enums.cpp:21:3:21:21 | myLocalEnumConstant | myLocalEnumConstant | 1 | myLocalEnum | 1 | 1 | 1 |
+| enums.cpp:29:5:29:24 | MyNestedEnumConstant | MyNestedEnumConstant | 1 | MyNestedEnum | 1 | 1 | 1 |
 | enums.ms.c:2:3:2:6 | zero | zero | 1 | numbers | 1 | 1 | 1 |
 | enums.ms.c:2:9:2:11 | one | one | 1 | numbers | 1 | 1 | 1 |
 | scoped.cpp:3:5:3:5 | X | X | 1 | E1 | 1 | 1 | 1 |

cpp/ql/test/library-tests/enums/enums/Enums3.expected

@@ -1,8 +1,10 @@
-| enums.cpp:3:6:3:8 | Day | false |
-| enums.cpp:4:6:4:9 | Day2 | false |
-| enums.cpp:5:6:5:9 | Flag | false |
-| enums.ms.c:1:6:1:12 | numbers | false |
-| scoped.cpp:2:12:2:13 | E1 | true |
-| scoped.cpp:6:12:6:13 | E2 | true |
-| scoped.cpp:10:13:10:14 | E3 | true |
-| scoped.cpp:16:14:16:18 | State | true |
+| enums.cpp:3:6:3:8 | Day |  |
+| enums.cpp:4:6:4:9 | Day2 |  |
+| enums.cpp:5:6:5:9 | Flag |  |
+| enums.cpp:19:7:19:17 | myLocalEnum | LocalEnum |
+| enums.cpp:27:8:27:19 | MyNestedEnum | NestedEnum |
+| enums.ms.c:1:6:1:12 | numbers |  |
+| scoped.cpp:2:12:2:13 | E1 | ScopedEnum |
+| scoped.cpp:6:12:6:13 | E2 | ScopedEnum |
+| scoped.cpp:10:13:10:14 | E3 | ScopedEnum |
+| scoped.cpp:16:14:16:18 | State | NestedEnum, ScopedEnum |

cpp/ql/test/library-tests/enums/enums/Enums3.ql

@@ -1,6 +1,18 @@
 import cpp
 
-from Enum e, boolean isScoped
-where if e instanceof ScopedEnum then isScoped = true else isScoped = false
-select e, isScoped
+string describe(Enum e)
+{
+  (
+    e instanceof LocalEnum and
+    result = "LocalEnum"
+  ) or (
+    e instanceof NestedEnum and
+    result = "NestedEnum"
+  ) or (
+    e instanceof ScopedEnum and
+    result = "ScopedEnum"
+  )
+}
 
+from Enum e
+select e, concat(describe(e), ", ")

cpp/ql/test/library-tests/enums/enums/enums.cpp

@@ -13,3 +13,19 @@ Day& operator++(Day& d)
 	Day2 d2 = (Day2)d;
 	return d = (sat==d) ? sun: Day(d+1);
 }
+
+void myFunction()
+{
+	enum myLocalEnum
+	{
+		myLocalEnumConstant
+	};
+};
+
+class MyClass
+{
+  enum MyNestedEnum
+  {
+    MyNestedEnumConstant
+  };
+};