Add some more doc comments

Author: odersky

compiler/src/dotty/tools/dotc/cc/Capability.scala

@@ -553,9 +553,10 @@ object Capabilities:
      */
     def hiddenSet(using Context): Refs = computeHiddenSet(identity)
 
-    /** Compute hidden set of this capability.
+    /** Compute result based on hidden set of this capability.
      *  Restrictions and read-only status transfer from the capability to its
      *  hidden set.
+     *  @param  f   a function that gets applied to all detected hidden sets
      */
     def computeHiddenSet(f: Refs => Refs)(using Context): Refs = this match
       case self: FreshCap => f(self.hiddenSet.elems)

compiler/src/dotty/tools/dotc/cc/CaptureOps.scala

@@ -151,24 +151,37 @@ extension (tp: Type)
     case tp: ObjectCapability => tp.captureSetOfInfo
     case _ => CaptureSet.ofType(tp, followResult = false)
 
-  /** The deep capture set of a type. This is by default the union of all
+  /** Compute a captureset by traversing parts of this type. This is by default the union of all
    *  covariant capture sets embedded in the widened type, as computed by
    *  `CaptureSet.ofTypeDeeply`. If that set is nonempty, and the type is
    *  a singleton capability `x` or a reach capability `x*`, the deep capture
    *  set can be narrowed to`{x*}`.
+   *  @param includeTypevars  if true, return a new FreshCap for every type parameter
+   *                          or abstract type with an Any upper bound. Types with
+   *                          defined upper bound are always mapped to the dcs of their bound
+   *  @param includeBoxed     if true, include capture sets found in boxed parts of this type
    */
-  def deepCaptureSet(includeTypevars: Boolean, includeBoxed: Boolean = true)(using Context): CaptureSet =
+  def computeDeepCaptureSet(includeTypevars: Boolean, includeBoxed: Boolean = true)(using Context): CaptureSet =
     val dcs = CaptureSet.ofTypeDeeply(tp.widen.stripCapturing, includeTypevars, includeBoxed)
     if dcs.isAlwaysEmpty then tp.captureSet
     else tp match
       case tp: ObjectCapability if tp.isTrackableRef => tp.reach.singletonCaptureSet
       case _ => tp.captureSet ++ dcs
 
+  /** The deep capture set of a type. This is by default the union of all
+   *  covariant capture sets embedded in the widened type, as computed by
+   *  `CaptureSet.ofTypeDeeply`. If that set is nonempty, and the type is
+   *  a singleton capability `x` or a reach capability `x*`, the deep capture
+   *  set can be narrowed to`{x*}`.
+   */
   def deepCaptureSet(using Context): CaptureSet =
-    deepCaptureSet(includeTypevars = false)
+    computeDeepCaptureSet(includeTypevars = false)
 
+  /** The span capture set of a type. This is analogous to deepCaptureSet but ignoring
+   *  capture sets in boxed parts.
+   */
   def spanCaptureSet(using Context): CaptureSet =
-    deepCaptureSet(includeTypevars = false, includeBoxed = false)
+    computeDeepCaptureSet(includeTypevars = false, includeBoxed = false)
 
   /** A type capturing `ref` */
   def capturing(ref: Capability)(using Context): Type =

compiler/src/dotty/tools/dotc/cc/CaptureSet.scala

@@ -950,8 +950,6 @@ object CaptureSet:
     override def toString = s"Var$id$elems"
   end Var
 
-  inline val strictFreshLevels = true
-
   /** Variables created in types of inferred type trees */
   class ProperVar(override val owner: Symbol, initialElems: Refs = emptyRefs, nestedOK: Boolean = true, isRefining: Boolean)(using /*@constructorOnly*/ ictx: Context)
   extends Var(owner, initialElems, nestedOK):
@@ -971,7 +969,7 @@ object CaptureSet:
         def fail = i"attempting to add $elem to $this"
         def hideIn(fc: FreshCap): Unit =
           assert(elem.tryClassifyAs(fc.hiddenSet.classifier), fail)
-          if strictFreshLevels && !isRefining then
+          if !isRefining then
             // If a variable is added by addCaptureRefinements in a synthetic
             // refinement of a class type, don't do level checking. The problem is
             // that the variable might be matched against a type that does not have
@@ -1560,7 +1558,7 @@ object CaptureSet:
   /** The capture set of the type underlying the capability `c` */
   def ofInfo(c: Capability)(using Context): CaptureSet = c match
     case Reach(c1) =>
-      c1.widen.deepCaptureSet(includeTypevars = true)
+      c1.widen.computeDeepCaptureSet(includeTypevars = true)
         .showing(i"Deep capture set of $c: ${c1.widen} = ${result}", capt)
     case Restricted(c1, cls) =>
       if cls == defn.NothingClass then CaptureSet.empty