C++: Add QLDoc for BufferMayWriteSideEffectFieldStoreQualifierNode

Author: MathiasVP

cpp/ql/src/semmle/code/cpp/ir/dataflow/internal/DataFlowPrivate.qll

@@ -325,6 +325,19 @@ private predicate fieldReadStep(Node node1, FieldContent f, Node node2) {
   )
 }
 
+/**
+ * When a store step happens in a function that looks like an array write such as:
+ * ```cpp
+ * void f(int* pa) {
+ *   pa = source();
+ * }
+ * ```
+ * it can be a write to an array, but it can also happen that `f` is called as `f(&a.x)`. If that is
+ * the case, the `ArrayContent` that was written by the call to `f` should be popped off the access
+ * path, and a `FieldContent` containing `x` should be pushed instead.
+ * So this case pops `ArrayContent` off the access path, and the `fieldStoreStepAfterArraySuppression`
+ * predicate in `storeStep` ensures that we push the right `FieldContent` onto the access path.
+ */
 predicate suppressArrayRead(Node node1, ArrayContent a, Node node2) {
   a = TArrayContent() and
   exists(BufferMayWriteSideEffectInstruction write, ChiInstruction chi |
@@ -383,17 +396,6 @@ private predicate arrayReadStep(Node node1, ArrayContent a, Node node2) {
 predicate readStep(Node node1, Content f, Node node2) {
   fieldReadStep(node1, f, node2) or
   arrayReadStep(node1, f, node2) or
-  // When a store step happens in a function that looks like an array write such as:
-  // ```cpp
-  // void f(int* pa) {
-  //   *pa = source();
-  // }
-  // ```
-  // it can be a write to an array, but it can also happen that `f` is called as `f(&a.x)`. If that is
-  // the case, the `ArrayContent` that was written by the call to `f` should be popped off the access
-  // path, and a `FieldContent` containing `x` should be pushed instead.
-  // So this case pops `ArrayContent` off the access path, and the `fieldStoreStepAfterArraySuppression`
-  // predicate in `storeStep` ensures that we push the right `FieldContent` onto the access path.
   suppressArrayRead(node1, f, node2)
 }
 

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

@@ -394,6 +394,12 @@ private FieldAddressInstruction getFieldInstruction(Instruction instr) {
   result = instr.(CopyValueInstruction).getUnary()
 }
 
+/**
+ * The target of a `fieldStoreStepAfterArraySuppression` store step, which is used to convert
+ * an `ArrayContent` to a `FieldContent` when the `BufferMayWriteSideEffect` instruction stores
+ * into a field. See the QLDoc for `suppressArrayRead` for an example of where such a conversion
+ * is inserted.
+ */
 private class BufferMayWriteSideEffectFieldStoreQualifierNode extends PartialDefinitionNode {
   override ChiInstruction instr;
   BufferMayWriteSideEffectInstruction write;