Merge pull request #6515 from MathiasVP/clarify-initialization-vs-assignment-in-docs

C++: Clarify difference between 'Initializer' and 'Assignment'.

cpp/ql/lib/semmle/code/cpp/Initializer.qll

@@ -18,6 +18,12 @@ import semmle.code.cpp.controlflow.ControlFlowGraph
  *   ...
  * }
  * ```
+ * But _not_ `4` in the following code:
+ * ```
+ * int myUninitializedVariable;
+ * myUninitializedVariable = 4;
+ * ```
+ * Instead, this is an `Assignment`.
  */
 class Initializer extends ControlFlowNode, @initialiser {
   override Location getLocation() { initialisers(underlyingElement(this), _, _, result) }

cpp/ql/lib/semmle/code/cpp/Variable.qll

@@ -136,6 +136,12 @@ class Variable extends Declaration, @variable {
   /**
    * Gets an assignment expression that assigns to this variable.
    * For example: `x=...` or `x+=...`.
+   *
+   * This does _not_ include the initialization of the variable. Use
+   * `Variable.getInitializer()` to get the variable's initializer,
+   * or use `Variable.getAnAssignedValue()` to get an expression that
+   * is the right-hand side of an assignment or an initialization of
+   * the varible.
    */
   Assignment getAnAssignment() { result.getLValue() = this.getAnAccess() }
 

cpp/ql/lib/semmle/code/cpp/exprs/Assignment.qll

@@ -5,7 +5,8 @@ import semmle.code.cpp.exprs.BitwiseOperation
 /**
  * A non-overloaded binary assignment operation, including `=`, `+=`, `&=`,
  * etc. A C++ overloaded assignment operation looks syntactically identical but is instead
- * a `FunctionCall`.
+ * a `FunctionCall`. This class does _not_ include variable initializers. To get a variable
+ * initializer, use `Initializer` instead.
  *
  * This is a QL base class for all (non-overloaded) assignments.
  */
@@ -34,6 +35,8 @@ class Assignment extends Operation, @assign_expr {
  * ```
  * a = b;
  * ```
+ * Note that `int a = b;` is _not_ an `AssignExpr`. It is a `Variable`,
+ * and `b` can be obtained using `Variable.getInitializer()`.
  */
 class AssignExpr extends Assignment, @assignexpr {
   override string getOperator() { result = "=" }
@@ -46,6 +49,9 @@ class AssignExpr extends Assignment, @assignexpr {
 
 /**
  * A non-overloaded binary assignment operation other than `=`.
+ *
+ * This class does _not_ include variable initializers. To get a variable
+ * initializer, use `Initializer` instead.
  */
 class AssignOperation extends Assignment, @assign_op_expr {
   override string toString() { result = "... " + this.getOperator() + " ..." }