Add doc comments

Author: odersky

compiler/src/dotty/tools/dotc/core/OrderingConstraint.scala

@@ -277,16 +277,28 @@ class OrderingConstraint(private val boundsMap: ParamBounds,
       case _ =>
         traverseChildren(t)
 
+  /** Adjust dependencies to account for the delta of previous entry `prevEntry`
+   *  and new bound `entry` for the type variable `tvar`.
+   */
   def adjustDeps(entry: Type | Null, prevEntry: Type | Null, tvar: Type | Null)(using Context): this.type =
     tvar match
       case tvar: TypeVar =>
         val adjuster = new Adjuster(tvar)
 
+        /** Adjust reverse depemdencies of all type variables referenced by `bound`
+         *  @param  isLower `bound` is a lower bound
+         *  @param  add     if true, add referenced variables to dependencoes, otherwise drop them.
+         */
         def adjustReferenced(bound: Type, isLower: Boolean, add: Boolean) =
           adjuster.variance = if isLower then 1 else -1
           adjuster.add = add
           adjuster.traverse(bound)
 
+        /** Use an optimized strategy to adjust dependencies to account for the delta
+         *  of previous bound `prevBound` and new bound `bound`: If `prevBound` is some
+         *  and/or prefix of `bound`, just add the new parts of `bound`.
+         *  @param  isLower `bound` and `prevBound` are lower bounds
+         */
         def adjustDelta(bound: Type, prevBound: Type, isLower: Boolean): Boolean =
           if bound eq prevBound then true
           else bound match
@@ -297,6 +309,10 @@ class OrderingConstraint(private val boundsMap: ParamBounds,
               }
             case _ => false
 
+        /** Adjust dependencies to account for the delta of previous bound `prevBound`
+         *  and new bound `bound`.
+         *  @param  isLower `bound` and `prevBound` are lower bounds
+         */
         def adjustBounds(bound: Type, prevBound: Type, isLower: Boolean) =
           if !adjustDelta(bound, prevBound, isLower) then
             adjustReferenced(prevBound, isLower, add = false)
@@ -322,19 +338,25 @@ class OrderingConstraint(private val boundsMap: ParamBounds,
     this
   end adjustDeps
 
+  /** Adjust dependencies to account for adding or dropping `entries` to the
+   *  constraint.
+   *  @param add   if true, entries is added, otherwise it is dropped
+   */
   def adjustDeps(entries: Array[Type], add: Boolean)(using Context): this.type =
     for n <- 0 until paramCount(entries) do
       if add
       then adjustDeps(entries(n), NoType, typeVar(entries, n))
       else adjustDeps(NoType, entries(n), typeVar(entries, n))
     this
 
+  /** If `tp` is a type variable, remove all its reverse dependencies */
   def dropDeps(tp: Type)(using Context): Unit = tp match
     case tv: TypeVar =>
       coDeps = coDeps.remove(tv)
       contraDeps = contraDeps.remove(tv)
     case _ =>
 
+  /** A string representing the two depenecy maps */
   def depsToString(using Context): String =
     def depsStr(deps: SimpleIdentityMap[TypeVar, TypeVars]): String =
       def depStr(tv: TypeVar) = i"$tv --> ${deps(tv).nn.toList}%, %"