C++: Add more comments.

Author: MathiasVP

cpp/ql/lib/semmle/code/cpp/ir/dataflow/internal/DataFlowUtil.qll

@@ -280,7 +280,24 @@ class Node extends TIRDataFlowNode {
    * - For (6) there are two results:
    *   - For the definition generated by `x += 2` the result is `x += 2`
    *   - For the definition generated by `int y = ...` the result is
-   *     also `x += 2`
+   *     also `x += 2`.
+   *
+   * For assignments, `node.asDefinition()` and `node.asExpr()` will both exist
+   * for the same dataflow node. However, for expression such as `x++` that
+   * both write to `x` and read the current value of `x`, `node.asDefinition()`
+   * will give you the node corresponding to the value after the increment, and
+   * `node.asExpr()` will give the node corresponding to the value before the
+   * increment. For an example of where this patterns, consider the following:
+   *
+   * ```cpp
+   * sink(x++);
+   * ```
+   * in the above program, there will not be flow from the node `n` such that
+   * `n.asDefinition() instanceof IncrementOperation` to the argument of `sink`
+   * since the value passed to `sink` is the value before to the increment.
+   * However, there will be dataflow from the node `n` such that
+   * `n.asExpr() instanceof IncrementOperation` since the result of evaluating
+   * the expression `x++` is passed to `sink`.
    */
   Expr asDefinition() {
     exists(StoreInstruction store |