Merge pull request #1859 from geoffw0/qldocpartialdef

CPP: Document PartialDefinitions

Author: jbj

cpp/ql/src/semmle/code/cpp/dataflow/internal/FlowVar.qll

@@ -84,8 +84,13 @@ cached class FlowVar extends TFlowVar {
  *
  * In contrast to a normal "definition", which provides a new value for
  * something, a partial definition is an expression that may affect a
- * value, but does not necessarily replace it entirely. For example,
- * `x.y = 1;` is a partial definition of the object `x`.
+ * value, but does not necessarily replace it entirely. For example:
+ * ```
+ * x.y = 1; // a partial definition of the object `x`.
+ * x.y.z = 1; // a partial definition of the objects `x` and `x.y`.
+ * x.setY(1); // a partial definition of the object `x`.
+ * setY(&x); // a partial definition of the object `x`.
+ * ```
  */
 private module PartialDefinitions {
   private newtype TPartialDefinition =
@@ -121,8 +126,19 @@ private module PartialDefinitions {
 
     predicate partiallyDefinesThis(ThisExpr e) { definedExpr = e }
 
+    /**
+     * Gets the subBasicBlock where this `PartialDefinition` is defined.
+     */
     ControlFlowNode getSubBasicBlockStart() { result = node }
 
+    /**
+     * Gets the expression that is being partially defined. For example in the
+     * following code:
+     * ```
+     * x.y = 1;
+     * ```
+     * The expression `x` is being partially defined.
+     */
     Expr getDefinedExpr() { result = definedExpr }
 
     Location getLocation() {

cpp/ql/test/library-tests/dataflow/partialdefinitions/partialdefinitions.cpp

@@ -0,0 +1,16 @@
+
+struct MyStruct
+{
+	int x;
+	struct MySubStruct {
+		int z;
+	} y;
+};
+
+void test()
+{
+	MyStruct s;
+
+	s.x = 1;
+	s.y.z = 1;
+}

cpp/ql/test/library-tests/dataflow/partialdefinitions/partialdefinitions.expected

@@ -0,0 +1,3 @@
+| partialdefinitions.cpp:14:2:14:2 | partial def of s | partialdefinitions.cpp:14:2:14:2 | s | partialdefinitions.cpp:14:2:14:8 | ... = ... |
+| partialdefinitions.cpp:15:2:15:2 | partial def of s | partialdefinitions.cpp:15:2:15:2 | s | partialdefinitions.cpp:15:2:15:10 | ... = ... |
+| partialdefinitions.cpp:15:4:15:4 | partial def of y | partialdefinitions.cpp:15:4:15:4 | y | partialdefinitions.cpp:15:2:15:10 | ... = ... |

cpp/ql/test/library-tests/dataflow/partialdefinitions/partialdefinitions.ql

@@ -0,0 +1,4 @@
+import semmle.code.cpp.dataflow.internal.FlowVar
+
+from PartialDefinition def
+select def, def.getDefinedExpr(), def.getSubBasicBlockStart()