Add more comments

Author: noti0na1

compiler/src/dotty/tools/dotc/ast/untpd.scala

@@ -537,8 +537,15 @@ object untpd extends Trees.Instance[Untyped] with UntypedTreeInfo {
       annot = New(annot, Nil)
     else
       val trefs =
-        if refs.isEmpty then ref(defn.NothingType)
-        else refs.map(SingletonTypeTree).reduce[Tree]((a, b) => makeOrType(a, b))
+        if refs.isEmpty then
+          // The NothingType is used to represent the empty capture set.
+          ref(defn.NothingType)
+        else
+          // Treat all references as term references before typing.
+          // A dummy term symbol will be created for each capture variable,
+          // and references to them will be replaced with the corresponding
+          // type references during typing.
+          refs.map(SingletonTypeTree).reduce[Tree]((a, b) => makeOrType(a, b))
       annot = New(AppliedTypeTree(annot, trefs :: Nil), Nil)
       annot.putAttachment(RetainsAnnot, ())
     Annotated(parent, annot)

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

@@ -58,8 +58,7 @@ extension (tree: Tree)
         tree.putAttachment(Captures, refs)
         refs
 
-  /** The type representing the capture set of retains annotation.
-   */
+  /** The type representing the capture set of @retains, @retainsCap or @retainsByName annotation. */
   def retainedSet(using Context): Type =
     tree match
       case Apply(TypeApply(_, refs :: Nil), _) => refs.tpe
@@ -93,8 +92,7 @@ extension (tp: Type)
       if tp.isNothingType then Nil
       else tp :: Nil // should be checked by wellformedness
 
-  /** A list of capabilities tof a retained set.
-   */
+  /** A list of capabilities of a retained set. */
   def retainedElements(using Context): List[Capability] =
     retainedElementsRaw.map(_.toCapability)
 
@@ -530,6 +528,9 @@ class CleanupRetains(using Context) extends TypeMap:
         RetainingType(tp, defn.NothingType, byName = annot.symbol == defn.RetainsByNameAnnot)
       case _ => mapOver(tp)
 
+/** A base class for extractors that match annotated types with a specific
+ *  Capability annotation.
+ */
 abstract class AnnotatedCapability(annotCls: Context ?=> ClassSymbol):
   def apply(tp: Type)(using Context): AnnotatedType =
     AnnotatedType(tp, Annotation(annotCls, util.Spans.NoSpan))

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

@@ -318,6 +318,7 @@ object NamerOps:
 
   /** Add a dummy term symbol for a type def that has capture parameter flag.
    *  The dummy symbol has the same name as the original type symbol and is stable.
+   *  The underlying info stores the corresponding type reference.
    *
    *  @param param the original type symbol of the capture parameter
    */

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

@@ -786,6 +786,8 @@ object SymDenotations {
       *
       * However, a stable member might not yet be initialized (if it is an object or anyhow lazy).
       * So the first call to a stable member might fail and/or produce side effects.
+      *
+      * Note, (f: => T) is treated as a stable TermRef only in Capture Sets.
       */
     final def isStableMember(using Context): Boolean = {
       def isUnstableValue =

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

@@ -770,6 +770,7 @@ object Types extends TypeUtils {
         case tp: ClassInfo => tp.appliedRef
         case _ => widenIfUnstable
       }
+      // The dummy term capture variable can only be found in a capture set.
       val excluded1 = if ctx.mode.is(Mode.InCaptureSet) then excluded else excluded | CaptureParam
       findMember(name, pre, required, excluded1)
     }

compiler/src/dotty/tools/dotc/typer/TypeAssigner.scala

@@ -162,6 +162,7 @@ trait TypeAssigner {
             // if this fails.
             ctx.javaFindMember(name, pre, lookInCompanion = false)
           else
+            // The dummy term capture variable can only be found in a capture set.
             val excluded = if ctx.mode.is(Mode.InCaptureSet) then EmptyFlags else CaptureParam
             qualType.findMember(name, pre, excluded = excluded)
 

compiler/src/dotty/tools/dotc/typer/Typer.scala

@@ -626,6 +626,7 @@ class Typer(@constructorOnly nestingLevel: Int = 0) extends Namer
       val saved2 = foundUnderScala2
       unimported = Set.empty
       foundUnderScala2 = NoType
+      // The dummy term capture variable can only be found in a capture set.
       val excluded = if ctx.mode.is(Mode.InCaptureSet) then EmptyFlags else CaptureParam
       try
         val found = findRef(name, pt, EmptyFlags, excluded, tree.srcPos)
@@ -2533,6 +2534,8 @@ class Typer(@constructorOnly nestingLevel: Int = 0) extends Namer
   def typedSingletonTypeTree(tree: untpd.SingletonTypeTree)(using Context): Tree = {
     val ref1 = typedExpr(tree.ref, SingletonTypeProto)
     if ctx.mode.is(Mode.InCaptureSet) && ref1.symbol.is(Flags.CaptureParam) then
+      // When a dummy term capture variable is found, it is replaced with
+      // the corresponding type references (stored in the underling types).
       return Ident(ref1.tpe.widen.asInstanceOf[TypeRef]).withSpan(tree.span)
     checkStable(ref1.tpe, tree.srcPos, "singleton type")
     assignType(cpy.SingletonTypeTree(tree)(ref1), ref1)