Nice capture-set rendering

Author: bracevac

scaladoc/src/dotty/tools/scaladoc/cc/CaptureOps.scala

@@ -1,29 +1,86 @@
-package dotty.tools.scaladoc.cc
+package dotty.tools.scaladoc
+
+package cc
 
 import scala.quoted._
 
 object CaptureDefs:
-  /** The name of the `retains` annotation. */
-  val RetainsName: String = "scala.annotation.retains"
-
-  /** The name of the `retainsCap` annotation. */
-  val RetainsCapName: String = "scala.annotation.retainsCap"
+  // these should become part of the reflect API in the distant future
+  def retains(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.annotation.retains")
+  def retainsCap(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.annotation.retainsCap")
+  def retainsByName(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.annotation.retainsByName")
+  def CapsModule(using qctx: Quotes) = qctx.reflect.Symbol.requiredPackage("scala.caps")
+  def captureRoot(using qctx: Quotes) = qctx.reflect.Symbol.requiredPackage("scala.caps.cap")
+  def Caps_Capability(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.Capability")
+  def Caps_CapSet(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.CapSet")
+  def Caps_Mutable(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.Mutable")
+  def Caps_SharedCapability(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.SharedCapability")
 
-  /** The name of the `retainsByName` annotation. */
-  val RetainsByNameName: String = "scala.annotation.retainsByName"
+  def UseAnnot(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.use")
+  def ConsumeAnnot(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass("scala.caps.consume")
 
-  def retains(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass(RetainsName)
-  def retainsCap(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass(RetainsCapName)
-  def retainsByName(using qctx: Quotes) = qctx.reflect.Symbol.requiredClass(RetainsByNameName)
 end CaptureDefs
 
-extension (using qctx: Quotes)(term: qctx.reflect.Term)
-
-  /** Is this term a `retains`* annotations from capturing types?  */
+extension (using qctx: Quotes)(ann: qctx.reflect.Symbol)
+  /** This symbol is one of `retains` or `retainsCap` */
   def isRetains: Boolean =
-    val sym = term.tpe match
-      case qctx.reflect.AppliedType(base, _) => base.typeSymbol
-      case other                             => other.typeSymbol
-    sym == CaptureDefs.retains
-    || sym == CaptureDefs.retainsCap
-    || sym == CaptureDefs.retainsByName
+    ann == CaptureDefs.retains || ann == CaptureDefs.retainsCap
+
+  /** This symbol is one of `retains`, `retainsCap`, or `retainsByName` */
+  def isRetainsLike: Boolean =
+    ann.isRetains || ann == CaptureDefs.retainsByName
+end extension
+
+extension (using qctx: Quotes)(tpe: qctx.reflect.TypeRepr)
+  def isCaptureRoot: Boolean = tpe.termSymbol == CaptureDefs.captureRoot
+end extension
+
+/** Decompose capture sets in the union-type-encoding into the sequence of atomic `TypeRepr`s.
+ *  Returns `None` if the type is not a capture set.
+*/
+def decomposeCaptureRefs(using qctx: Quotes)(typ0: qctx.reflect.TypeRepr): Option[List[qctx.reflect.TypeRepr]] =
+  import qctx.reflect._
+  val buffer = collection.mutable.ListBuffer.empty[TypeRepr]
+  def traverse(typ: TypeRepr): Boolean =
+    typ match
+      case OrType(t1, t2)     => traverse(t1) && traverse(t2)
+      case t @ ThisType(_)    => buffer += t; true
+      case t @ TermRef(_, _)  => buffer += t; true
+      case t @ ParamRef(_, _) => buffer += t; true
+       // TODO: are atoms only ever the above? Then we could refine the return type
+      case _ => report.warning(s"Unexpected type tree $typ while trying to extract capture references from $typ0"); System.exit(1); false // TODO remove warning eventually
+  if traverse(typ0) then Some(buffer.toList) else None
+end decomposeCaptureRefs
+
+object CaptureSetType:
+  def unapply(using qctx: Quotes)(tt: qctx.reflect.TypeTree): Option[List[qctx.reflect.TypeRepr]] = decomposeCaptureRefs(tt.tpe)
+end CaptureSetType
+
+object CapturingType:
+  def unapply(using qctx: Quotes)(typ: qctx.reflect.TypeRepr): Option[(qctx.reflect.TypeRepr, List[qctx.reflect.TypeRepr])] =
+    import qctx.reflect._
+    typ match
+      case AnnotatedType(base, Apply(TypeApply(Select(New(annot), _), List(CaptureSetType(refs))), Nil)) if annot.symbol.isRetainsLike =>
+        Some((base, refs))
+      case AnnotatedType(base, Apply(Select(New(annot), _), Nil)) if annot.symbol == CaptureDefs.retainsCap =>
+        Some((base, List(CaptureDefs.captureRoot.termRef)))
+      case _ => None
+end CapturingType
+
+def renderCaptureSet(using qctx: Quotes)(refs: List[qctx.reflect.TypeRepr]): List[SignaturePart] =
+  import dotty.tools.scaladoc.tasty.NameNormalizer._
+  import qctx.reflect._
+  refs match
+    case List(ref) if ref.isCaptureRoot => List(Keyword("^"))
+    case refs =>
+      val res0 = refs.map { ref =>
+        ref match
+          case ThisType(_) => List(Keyword("this"))
+          case TermRef(_, sym) => List(Plain(sym)) // FIXME: use type other than Plain, can we have clickable links to say, caps.cap and other things?
+          case pf @ ParamRef(tpe, i) => List(Plain(tpe.asInstanceOf[MethodType].paramNames(i))) // FIXME: not sure if this covers all cases
+          case _ => List(Plain("<unknown>"))
+      }
+      val res1 = res0 match
+        case Nil => Nil
+        case other => other.reduce((r, e) => r ++ (List(Plain(", ")) ++ e))
+      Keyword("^") :: Plain("{") :: (res1 ++ List(Plain("}")))

scaladoc/src/dotty/tools/scaladoc/tasty/NameNormalizer.scala

@@ -17,16 +17,16 @@ object NameNormalizer {
       val escaped = escapedName(constructorNormalizedName)
       escaped
     }
-    
+
     def ownerNameChain: List[String] = {
       import reflect.*
       if s.isNoSymbol then List.empty
       else if s == defn.EmptyPackageClass then List.empty
       else if s == defn.RootPackage then List.empty
       else if s == defn.RootClass then List.empty
       else s.owner.ownerNameChain :+ s.normalizedName
-    }  
-      
+    }
+
     def normalizedFullName: String =
       s.ownerNameChain.mkString(".")
 

scaladoc/src/dotty/tools/scaladoc/tasty/TypesSupport.scala

@@ -107,7 +107,16 @@ trait TypesSupport:
         inParens(inner(left, skipThisTypePrefix), shouldWrapInParens(left, tp, true))
         ++ keyword(" & ").l
         ++ inParens(inner(right, skipThisTypePrefix), shouldWrapInParens(right, tp, false))
-      case ByNameType(tpe) => keyword("=> ") :: inner(tpe, skipThisTypePrefix)
+      case CapturingType(base, refs) =>
+        inner(base, skipThisTypePrefix) ++ renderCaptureSet(refs)
+      case ByNameType(CapturingType(tpe, refs)) =>
+        refs match
+          case Nil => keyword("-> ") :: inner(tpe, skipThisTypePrefix)
+          case List(ref) if ref.isCaptureRoot =>
+            keyword("=> ") :: inner(tpe, skipThisTypePrefix)
+          case refs =>
+            keyword("->") :: (renderCaptureSet(refs) ++ inner(tpe, skipThisTypePrefix))
+      case ByNameType(tpe) => keyword("=> ") :: inner(tpe, skipThisTypePrefix) // FIXME: does it need change for CC?
       case ConstantType(constant) =>
         plain(constant.show).l
       case ThisType(tpe) =>
@@ -118,8 +127,6 @@ trait TypesSupport:
         inner(tpe, skipThisTypePrefix) :+ plain("*")
       case AppliedType(repeatedClass, Seq(tpe)) if isRepeated(repeatedClass) =>
         inner(tpe, skipThisTypePrefix) :+ plain("*")
-      case AnnotatedType(tpe, annotTerm) if annotTerm.isRetains =>
-        inner(tpe, skipThisTypePrefix) :+ plain(" @retains") // FIXME
       case AnnotatedType(tpe, _) =>
         inner(tpe, skipThisTypePrefix)
       case tl @ TypeLambda(params, paramBounds, AppliedType(tpe, args))