1 files changed, 24 insertions, 7 deletions

diff --git a/src/dotty/tools/dotc/core/Referenceds.scala b/src/dotty/tools/dotc/core/Referenceds.scala
index 61f95e0e0..f0db3ff6c 100644
--- a/src/dotty/tools/dotc/core/Referenceds.scala
+++ b/src/dotty/tools/dotc/core/Referenceds.scala
@@ -71,7 +71,7 @@ object Referenceds {
     /** The type info of the reference, exists only for non-overloaded references */
     def info: Type
 
-    /** The interval during which this reference is valid */
+    /** The period during which this reference is valid. */
     def validFor: Period
 
     /** Is this a reference to a type symbol? */
@@ -215,9 +215,26 @@ object Referenceds {
 
     // ------ Transformations -----------------------------------------
 
-    var validFor: Period = Nowhere
-
-    /** The next SymRefd in this run, with wrap-around from last to first. */
+    private[this] var _validFor: Period = Nowhere
+
+    def validFor = _validFor
+    def validFor_=(p: Period) =
+      _validFor = p
+
+    /** The next SymRefd in this run, with wrap-around from last to first.
+     *
+     *  There may be several `SymRefd`s with different validity
+     *  representing the same underlying definition at different phases.
+     *  These are called a "flock". Flock members are generated by
+     *  @see SymRef.current. Flock members are connected in a ring
+     *  with their `nextInRun` fields.
+     *
+     *  There are the following invariants converning flock members
+     *
+     *  1) validity periods must be non-overlapping
+     *  2) the union of all validity periods must be a contiguous
+     *     interval starting in FirstPhaseId.
+     */
     var nextInRun: SymRefd = this
 
     /** The version of this SymRefd that was valid in the first phase
@@ -225,13 +242,13 @@ object Referenceds {
      */
     def initial: SymRefd = {
       var current = nextInRun
-      while (current.validFor.code > this.validFor.code) current = current.nextInRun
+      while (current.validFor.code > this._validFor.code) current = current.nextInRun
       current
     }
 
     def current(implicit ctx: Context): SymRefd = {
       val currentPeriod = ctx.period
-      val valid = validFor
+      val valid = _validFor
       var current = this
       if (currentPeriod.code > valid.code) {
         // search for containing period as long as nextInRun increases.
@@ -242,7 +259,7 @@ object Referenceds {
           next = next.nextInRun
         }
         if (next.validFor.code > valid.code) {
-          // in this case, containsPeriod(next.validFor, currentPeriod)
+          // in this case, containsPeriod(next._validFor, currentPeriod)
           current = next
         } else {
           // not found, current points to highest existing variant