anchor.diff:  }
   ----
   
  -<<shadowVariableIntroduction,Register this class as a planning entity.>>
  +<<shadowVariableIntroduction,Register this class as a planning entity>>,
  +otherwise Planner won't detect it and the shadow variable won't update.
   
   [WARNING]
   ====
  
positive.code:     }
  ----
  
  <<shadowVariableIntroduction,Register this class as a planning entity.>>
  The `variableName` is the (genuine or shadow) variable that triggers changes to this shadow variable.
  
  [NOTE]
  ====
  If the class of the trigger variable is different than the shadow variable, also specify the `entityClass` on ``@PlanningVariableReference``.
  In that case, make sure that `entityClass` is also properly configured as a planning entity class in the solver config, or the `VariableListener` will simply never trigger.
  ====
  
  For example, the `VehicleUpdatingVariableListener` assures that every `Customer` in a chain has the same ``Vehicle``, namely the chain's anchor.
  
negative.code: }
  ----
  
  <<shadowVariableIntroduction,Register this class as a planning entity>>,
  otherwise Planner won't detect it and the shadow variable won't update.
  The `sourceVariableName` property is the name of the genuine planning variable on the return type of the getter
  (so the name of the genuine planning variable on the _other_ side).
  
  [NOTE]
  ====
  The shadow property, which is ``Collection`` (usually `List`, `Set` or `SortedSet`), can never be ``null``.
  If no genuine variable references that shadow entity, then it is an empty collection.
  Furthermore it must be a mutable `Collection` because once Planner starts initializing or changing genuine planning variables,
  it will add and remove elements to the ``Collection``s of those shadow variables accordingly.
  ====
  
  For a chained planning variable, the bi-directional relationship is always a one to one relationship.
  