Merge pull request #1706 from geoffw0/qldoceg3

CPP: Add syntax examples to QLDoc in Struct.qll, Union.qll.

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

@@ -2,7 +2,18 @@ import semmle.code.cpp.Type
 import semmle.code.cpp.Class
 
 /**
- * A C/C++ structure or union.
+ * A C/C++ structure or union. For example, the types `MyStruct` and `MyUnion`
+ * in:
+ * ``` 
+ * struct MyStruct {
+ *   int x, y, z;
+ * };
+ *
+ * union MyUnion {
+ *   int i;
+ *   float f;
+ * };
+ * ```
  */
 class Struct extends Class {
 
@@ -16,7 +27,15 @@ class Struct extends Class {
 }
 
 /**
- * A C++ struct that is directly enclosed by a function.
+ * A C/C++ struct that is directly enclosed by a function. For example, the type
+ * `MyLocalStruct` in:
+ * ```
+ * void myFunction() { 
+ *   struct MyLocalStruct {
+ *     int x, y, z;
+ *   };
+ * }
+ * ```
  */
 class LocalStruct extends Struct {
   LocalStruct() {
@@ -28,7 +47,15 @@ class LocalStruct extends Struct {
 }
 
 /**
- * A C++ nested struct. See 11.12.
+ * A C/C++ nested struct. See 11.12. For example, the type `MyNestedStruct` in:
+ * ```
+ * class MyClass {
+ * public:
+ *   struct MyNestedStruct {
+ *     int x, y, z;
+ *   };
+ * };
+ * ```
  */
 class NestedStruct extends Struct {
   NestedStruct() {

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

@@ -2,7 +2,13 @@ import semmle.code.cpp.Type
 import semmle.code.cpp.Struct
 
 /**
- * A C/C++ union. See C.8.2.
+ * A C/C++ union. See C.8.2. For example, the type `MyUnion` in:
+ * ```
+ * union MyUnion {
+ *   int i;
+ *   float f;
+ * };
+ * ```
  */
 class Union extends Struct  {
 
@@ -17,7 +23,16 @@ class Union extends Struct  {
 }
 
 /**
- * A C++ union that is directly enclosed by a function.
+ * A C/C++ union that is directly enclosed by a function. For example, the type
+ * `MyLocalUnion` in:
+ * ```
+ * void myFunction() {
+ *   union MyLocalUnion {
+ *     int i;
+ *     float f;
+ *   };
+ * }
+ * ```
  */
 class LocalUnion extends Union {
   LocalUnion() {
@@ -28,7 +43,16 @@ class LocalUnion extends Union {
 }
 
 /**
- * A C++ nested union.
+ * A C/C++ nested union. For example, the type `MyNestedUnion` in:
+ * ```
+ * class MyClass {
+ * public:
+ *   union MyNestedUnion {
+ *     int i;
+ *     float f;
+ *   };
+ * };
+ * ```
  */
 class NestedUnion extends Union {
   NestedUnion() {

cpp/ql/test/library-tests/structs/structs/structs.c

@@ -10,3 +10,9 @@ void f(void) {
     l = s.i;
 } 
 
+void myFunction()
+{ 
+  struct MyLocalStruct {
+    int x, y, z;
+  };
+}

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

@@ -0,0 +1,8 @@
+
+class MyClass
+{
+public:
+  struct MyNestedStruct {
+    int x, y, z;
+  };
+};

cpp/ql/test/library-tests/structs/structs/structs.expected

@@ -1 +1,6 @@
+structs
+| structs.c:2:8:2:10 | foo |  |
+| structs.c:15:10:15:22 | MyLocalStruct | LocalStruct |
+| structs.cpp:5:10:5:23 | MyNestedStruct | NestedStruct |
+assignments
 | structs.c:10:5:10:11 | ... = ... | structs.c:10:5:10:5 | l | int | structs.c:10:11:10:11 | i | int |

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

@@ -1,9 +1,24 @@
 import cpp
 
-from Assignment a
-select a,
-       a.getLValue() as l,
-       l.getType().explain(),
-       a.getRValue() as r,
-       r.getType().explain()
+string describe(Struct s)
+{
+  (
+    s instanceof LocalStruct and
+    result = "LocalStruct"
+  ) or (
+    s instanceof NestedStruct and
+    result = "NestedStruct"
+  )
+}
 
+query predicate structs(Struct s, string descStr) {
+  s.fromSource() and
+  descStr = concat(describe(s), ", ")
+}
+
+query predicate assignments(Assignment a, Expr l, string explainL, Expr r, string explainR) {
+  l = a.getLValue() and
+  explainL = l.getType().explain() and
+  r = a.getRValue() and
+  explainR = r.getType().explain()
+}

cpp/ql/test/library-tests/unions/Unions1.expected

@@ -1,3 +1,6 @@
-| unions.cpp:4:8:4:12 | Entry | struct |  |
-| unions.cpp:13:7:13:11 | Value | struct | union |
-| unions.cpp:19:8:19:22 | EntryWithMethod | struct |  |
+| unions.cpp:4:8:4:12 | Entry | Struct |  | operator= |
+| unions.cpp:13:7:13:11 | Value | Struct, Union |  | operator= |
+| unions.cpp:19:8:19:22 | EntryWithMethod | Struct | Entry | getAsInt, operator= |
+| unions.cpp:27:9:27:20 | MyLocalUnion | LocalUnion, Struct, Union |  | operator= |
+| unions.cpp:33:7:33:13 | MyClass |  |  | operator= |
+| unions.cpp:36:9:36:21 | MyNestedUnion | NestedUnion, Struct, Union |  | operator= |

cpp/ql/test/library-tests/unions/Unions1.ql

@@ -1,6 +1,25 @@
 import cpp
 
-from Class t, string struct, string union
-where if t instanceof Struct then struct = "struct" else struct = ""
-  and if t instanceof Union  then union  = "union"  else union  = ""
-select t, struct, union
+string describe(Class c)
+{
+  (
+    c instanceof Struct and
+    result = "Struct"
+  ) or (
+    c instanceof Union and
+    result = "Union"
+  ) or (
+    c instanceof LocalUnion and
+    result = "LocalUnion"
+  ) or (
+    c instanceof NestedUnion and
+    result = "NestedUnion"
+  )
+}
+
+from Class c
+select
+  c,
+  concat(describe(c), ", "),
+  concat(c.getABaseClass().toString(), ", "),
+  concat(c.getAMemberFunction().toString(), ", ")

cpp/ql/test/library-tests/unions/Unions4.expected

@@ -1,3 +0,0 @@
-| unions.cpp:19:8:19:22 | EntryWithMethod | unions.cpp:4:8:4:12 | Entry | unions.cpp:19:8:19:8 | operator= |
-| unions.cpp:19:8:19:22 | EntryWithMethod | unions.cpp:4:8:4:12 | Entry | unions.cpp:19:8:19:8 | operator= |
-| unions.cpp:19:8:19:22 | EntryWithMethod | unions.cpp:4:8:4:12 | Entry | unions.cpp:20:7:20:14 | getAsInt |

cpp/ql/test/library-tests/unions/Unions4.ql

@@ -1,4 +0,0 @@
-import cpp
-
-from Struct s
-select s, s.getABaseClass(), s.getAMemberFunction()

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

@@ -21,3 +21,20 @@ struct EntryWithMethod: Entry {
 	  return i;
   }
 };
+
+void myFunction()
+{
+  union MyLocalUnion {
+    int i;
+    float f;
+  };
+}
+
+class MyClass
+{
+public:
+  union MyNestedUnion {
+    int i;
+    float f;
+  };
+};