Change scaladoc to the new syntax

Author: odersky

docs/_docs/reference/experimental/capture-checking/classes.md

@@ -325,10 +325,10 @@ def test(): Unit =
 ```
 Here, the initialization of `D` accesses the capability `out`. Therefore, the function value `() => D()` has type `() ->{out} D`.
 
-The capabilities accessed during initialization of a class can be declared in the class with a `uses_init` clause, like this:
+The capabilities accessed during initialization of a class can be declared in the class with a `uses` clause, where each accessed capability is followed by `initially`, like this:
 
 ```scala sc-compile-with:classes-external-context
-class D() uses_init out:
+class D() uses out initially:
   val str: String =
     out.println("str was initialized")
     "abc"
@@ -338,17 +338,33 @@ def test(): Unit =
   ()
 //}
 ```
-A `uses_init` clause must be given if a class that is visible in other compilation units accesses capabilities during initialization. Like for `uses` clauses, this is to support separate compilation where we need to know the use set of a class instance creation without analyzing the internals of the class.
+If a class uses a capability initially in its constructor and also retains it for further
+use in the created instance, the capability appears twice in the `uses` clause, once with `initially`
+and once without.
+
+```scala sc-compile-with:classes-external-context
+class D() uses out initially, out:
+  val str: String =
+    out.println("str was initialized")
+    "abc"
+  def print() = out.println(str)
+//{
+def test(): Unit =
+  val _: () ->{out} D^{out} = () => D()
+  ()
+//}
+```
+A `uses` clause must be given if a class that is visible in other compilation units accesses capabilities during initialization. Like for regular `uses` clauses, this is to support separate compilation where we need to know the use set of a class instance creation without analyzing the internals of the class.
 
 **Syntax**
 
-`uses` clauses come after `extends` and `derives` clauses. `uses_init` clauses come after `uses` clauses.
+A `uses` clause comes after `extends` and `derives` clauses.
 
 ```
 InheritClauses    ::=  [‘extends’ ConstrApps]
                        [‘derives’ QualId {‘,’ QualId}]
-                       [‘uses’ CaptureRef {‘,’ CaptureRef}]
-                       [‘uses_init’ CaptureRef {‘,’ CaptureRef}]
+                       [‘uses’ UseRef {‘,’ UseRef}]
+UseRef            ::=  CaptureRef [‘initially’]
 ```
 
 

scaladoc-testcases/src/tests/i25529.scala

@@ -10,7 +10,7 @@ class A extends SharedCapability:
 object ObjA extends ExclusiveCapability:
   val a: A^ = A()
 
-object ObjB uses_init ObjA: //expected: object ObjB uses_init ObjA
+object ObjB uses ObjA initially: //expected: object ObjB uses ObjA initially
   val x = ObjA.a.f()
 
 object ObjC uses ObjA: //expected: object ObjC uses ObjA

scaladoc/src/dotty/tools/scaladoc/api.scala

@@ -100,7 +100,7 @@ object Annotation:
   case class LinkParameter(name: Option[String] = None, dri: DRI, value: String) extends AnnotationParameter
   case class UnresolvedParameter(name: Option[String] = None, unresolvedText: String) extends AnnotationParameter
 
-case class UsesClause(keyword: String, signature: Signature)
+case class UsesClause(signature: Signature)
 
 case class TermParameterList(
   parameters: Seq[TermParameter],
@@ -167,7 +167,7 @@ case class Member(
   visibility: Visibility = Visibility.Unrestricted,
   modifiers: Seq[Modifier] = Nil,
   annotations: List[Annotation] = Nil,
-  usesClauses: List[UsesClause] = Nil,
+  usesClause: Option[UsesClause] = None,
   signature: Signature = Signature(),
   sources: Option[TastyMemberSource] = None,
   origin: Origin = Origin.RegularlyDefined,

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

@@ -73,19 +73,20 @@ trait ClassLikeSupport:
     else if classDef.symbol.flags.is(Flags.Enum) then Kind.Enum(typeArgs, args)
     else Kind.Class(typeArgs, args)
 
-  private def usesClausesFor(classDef: ClassDef): List[UsesClause] =
-    def clauseFrom(symbol: Symbol, keyword: String): Option[UsesClause] =
+  private def usesClauseFor(classDef: ClassDef): Option[UsesClause] =
+    def clauseFrom(symbol: Symbol, initially: Boolean): Option[SSignature] =
       for
         annot <- symbol.annotations.find(_.tpe.typeSymbol.isRetains)
         refs <- retainedCaptureRefs(annot)
         if refs.nonEmpty
-      yield UsesClause(keyword, emitCaptureRefsSignature(using qctx)(refs)(using classDef, classDef.symbol))
+      yield emitCaptureRefsSignature(using qctx)(refs, addInitially = initially)(using classDef, classDef.symbol)
 
-    if !ccEnabled then Nil
+    if !ccEnabled then None
     else
-      val uses = clauseFrom(classDef.symbol, "uses")
-      val usesInit = clauseFrom(classDef.constructor.symbol, "uses_init")
-      List(uses, usesInit).flatten
+      val constrUses = clauseFrom(classDef.constructor.symbol, initially = true)
+      val classUses = clauseFrom(classDef.symbol, initially = false)
+      val allUses = constrUses.getOrElse(Nil) ++ classUses.getOrElse(Nil)
+      Option.unless(allUses.isEmpty)(UsesClause(allUses))
 
   def mkClass(classDef: ClassDef)(
     dri: DRI = classDef.symbol.dri,
@@ -151,7 +152,7 @@ trait ClassLikeSupport:
     ).copy(
       directParents = classDef.getParentsAsLinkToTypes,
       parents = supertypes,
-      usesClauses = usesClausesFor(classDef)
+      usesClause = usesClauseFor(classDef)
     )
 
     if summon[DocContext].args.generateInkuire then doInkuireStuff(classDef)
@@ -569,7 +570,7 @@ trait ClassLikeSupport:
     visibility = symbol.getVisibility(),
     modifiers = modifiers,
     annotations = symbol.getAnnotations(),
-    usesClauses = Nil,
+    usesClause = None,
     signature = signature,
     sources = symbol.source,
     origin = origin,

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

@@ -550,12 +550,16 @@ trait TypesSupport:
       case ThisType(_)            => List(Keyword("this"))
       case t                      => inner(t, skipThisTypePrefix)(using skipTypeSuffix = true, inCC = Some(Nil))
 
-  protected def emitCaptureRefsSignature(using Quotes)(refs: List[reflect.TypeRepr], skipThisTypePrefix: Boolean = false)(using elideThis: reflect.ClassDef, originalOwner: reflect.Symbol): SSignature =
+  protected def emitCaptureRefsSignature(using Quotes)(refs: List[reflect.TypeRepr], skipThisTypePrefix: Boolean = false, addInitially: Boolean = false)(using elideThis: reflect.ClassDef, originalOwner: reflect.Symbol): SSignature =
     refs match
       case Nil => Nil
       case _ =>
+        def emitRef(ref: reflect.TypeRepr) =
+          val csig = emitCapability(ref, skipThisTypePrefix)
+          if addInitially then csig ++ List(plain(" "), Keyword("initially"))
+          else csig
         refs
-          .map(emitCapability(_, skipThisTypePrefix))
+          .map(emitRef)
           .reduce((left, right) => left ++ (Plain(", ") :: right))
 
   private def emitCaptureSet(using Quotes)(refs: List[reflect.TypeRepr], skipThisTypePrefix: Boolean, omitCap: Boolean = true)(using elideThis: reflect.ClassDef, originalOwner: reflect.Symbol): SSignature =

scaladoc/src/dotty/tools/scaladoc/translators/ScalaSignatureProvider.scala

@@ -61,7 +61,7 @@ class ScalaSignatureProvider:
         .typeParamList(kind.typeParams)
         .functionTermParameters(kind.argsLists)
         .parentsSignature(member)
-        .usesClauses(member)
+        .usesClause(member)
     )
 
 

scaladoc/src/dotty/tools/scaladoc/translators/ScalaSignatureUtils.scala

@@ -69,10 +69,10 @@ case class SignatureBuilder(content: Signature = Nil) extends ScalaSignatureUtil
         val extendPart = keyword(" extends ").signature(extendType.signature)
         withTypes.foldLeft(extendPart)((bdr2, tpe) => bdr2.keyword(", ").signature(tpe.signature))
 
-  def usesClauses(member: Member): SignatureBuilder =
-    member.usesClauses.foldLeft(this) { (bdr, clause) =>
-      bdr.keyword(s" ${clause.keyword} ").signature(clause.signature)
-    }
+  def usesClause(member: Member): SignatureBuilder =
+    member.usesClause match
+      case None => this
+      case Some(clause) => keyword(" uses ").signature(clause.signature)
 
   def modifiersAndVisibility(t: Member) =
     val (prefixMods, suffixMods) = t.modifiers.partition(_.prefix)