Skip to content

Commit 208232a

Browse files
felixmulderfelixmulder
committed
Implement docbase as property
1 parent af27562 commit 208232a

15 files changed

+87
-49
lines changed

‎dottydoc/src/dotty/tools/dottydoc/DottyDoc.scala

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package dotty.tools
22
package dottydoc
33

4+
import dotty.tools.dottydoc.util.syntax._
45
import core._
56
import core.transform._
67
import dotc.config.CompilerCommand
@@ -56,6 +57,7 @@ abstract class DocDriver extends Driver {
5657

5758
ctx.setSettings(summary.sstate)
5859
ctx.setSetting(ctx.settings.YkeepComments, true)
60+
ctx.setProperty(DocContext, new DocBase)
5961

6062
val fileNames = CompilerCommand.checkUsage(summary, sourcesRequired)(ctx)
6163
(fileNames, ctx)
@@ -67,7 +69,7 @@ abstract class DocDriver extends Driver {
6769
val (fileNames, ctx) = setup(args, initCtx.fresh)
6870
doCompile(newCompiler(ctx), fileNames)(ctx)
6971

70-
ctx.docbase.packages[Package]
72+
ctx.docbase.packages
7173
}
7274

7375
def compiledDocsJava(args: Array[String]): JMap[String, Package] =

‎dottydoc/src/dotty/tools/dottydoc/core/DocASTPhase.scala

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ package core
66
import dotc.ast.Trees._
77
import dotc.CompilationUnit
88
import dotc.config.Printers.dottydoc
9-
import dotc.core.Contexts.Context
9+
import dotc.core.Contexts.{ Context, DocBase }
1010
import dotc.core.Phases.Phase
1111
import dotc.core.Symbols.{ Symbol, NoSymbol }
1212

@@ -17,6 +17,7 @@ class DocASTPhase extends Phase {
1717
import model.comment.Comment
1818
import dotty.tools.dotc.core.Flags
1919
import dotty.tools.dotc.ast.tpd._
20+
import dotty.tools.dottydoc.util.syntax._
2021
import util.traversing._
2122
import util.internal.setters._
2223

@@ -161,7 +162,7 @@ class DocASTPhase extends Phase {
161162
} setParent(child, to = parent)
162163

163164
// (3) Update Doc AST in ctx.base
164-
for (kv <- packages) ctx.docbase.packages += kv
165+
for (kv <- packages) ctx.docbase.packagesMutable += kv
165166

166167
// Return super's result
167168
compUnits

‎dottydoc/src/dotty/tools/dottydoc/core/DocImplicitsPhase.scala

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ package core
55
import dotty.tools.dotc.transform.TreeTransforms.{ MiniPhaseTransform, TransformerInfo }
66
import dotty.tools.dotc.core.Flags
77
import dotc.core.Contexts.Context
8+
import util.syntax._
89

910
class DocImplicitsPhase extends MiniPhaseTransform { thisTransformer =>
1011
import dotty.tools.dotc.ast.tpd._

‎dottydoc/src/dotty/tools/dottydoc/core/DocstringPhase.scala

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@ import model._
88
import model.internal._
99
import model.comment._
1010
import BodyParsers._
11+
import util.syntax._
1112

1213
class DocstringPhase extends DocMiniPhase with CommentParser with CommentCleaner {
1314
private def parsedComment[E <: Entity](ent: E)(implicit ctx: Context): Option[Comment] =
1415
ctx.docbase.docstring(ent.symbol).map { cmt =>
15-
parse(ent, ctx.docbase.packages[Package].toMap, clean(cmt.raw), cmt.raw, cmt.pos)
16+
parse(ent, ctx.docbase.packages, clean(cmt.raw), cmt.raw, cmt.pos)
1617
.toComment(_.toHtml(ent))
1718
}
1819

‎dottydoc/src/dotty/tools/dottydoc/core/MiniPhaseTransform.scala

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,11 @@ package dottydoc
33
package core
44

55
import dotc.CompilationUnit
6-
import dotc.core.Contexts.Context
6+
import dotc.core.Contexts.{ Context, DocBase }
77
import dotc.core.Phases.Phase
88
import model._
99
import model.internal._
10+
import util.syntax._
1011

1112
object transform {
1213
/**
@@ -43,9 +44,9 @@ object transform {
4344
override def runOn(units: List[CompilationUnit])(implicit ctx: Context): List[CompilationUnit] = {
4445
for {
4546
rootName <- rootPackages
46-
pack = ctx.docbase.packages[Package](rootName)
47+
pack = ctx.docbase.packages(rootName)
4748
transformed = performPackageTransform(pack)
48-
} yield ctx.docbase.packages(rootName) = transformed
49+
} yield ctx.docbase.packagesMutable(rootName) = transformed
4950
super.runOn(units)
5051
}
5152

@@ -85,7 +86,7 @@ object transform {
8586
)
8687

8788
// Update reference in context to newPackage
88-
ctx.docbase.packages[Package] += (newPackage.path.mkString(".") -> newPackage)
89+
ctx.docbase.packagesMutable += (newPackage.path.mkString(".") -> newPackage)
8990

9091
newPackage
9192
}

‎dottydoc/src/dotty/tools/dottydoc/core/TypeLinkingPhases.scala

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,16 @@ import BodyParsers._
1414
import util.MemberLookup
1515
import util.traversing._
1616
import util.internal.setters._
17+
import util.syntax._
1718

1819
class LinkReturnTypes extends DocMiniPhase with TypeLinker {
1920
override def transformDef(implicit ctx: Context) = { case df: DefImpl =>
20-
val returnValue = linkReference(df, df.returnValue, ctx.docbase.packages[Package].toMap)
21+
val returnValue = linkReference(df, df.returnValue, ctx.docbase.packages)
2122
df.copy(returnValue = returnValue)
2223
}
2324

2425
override def transformVal(implicit ctx: Context) = { case vl: ValImpl =>
25-
val returnValue = linkReference(vl, vl.returnValue, ctx.docbase.packages[Package].toMap)
26+
val returnValue = linkReference(vl, vl.returnValue, ctx.docbase.packages)
2627
vl.copy(returnValue = returnValue)
2728
}
2829
}
@@ -31,7 +32,7 @@ class LinkParamListTypes extends DocMiniPhase with TypeLinker {
3132
override def transformDef(implicit ctx: Context) = { case df: DefImpl =>
3233
val newParamLists = for {
3334
ParamListImpl(list, isImplicit) <- df.paramLists
34-
newList = list.map(linkReference(df, _, ctx.docbase.packages[Package].toMap))
35+
newList = list.map(linkReference(df, _, ctx.docbase.packages))
3536
} yield ParamListImpl(newList.asInstanceOf[List[NamedReference]], isImplicit)
3637

3738
df.copy(paramLists = newParamLists)
@@ -42,7 +43,7 @@ class LinkSuperTypes extends DocMiniPhase with TypeLinker {
4243
def linkSuperTypes(ent: Entity with SuperTypes)(implicit ctx: Context): List[MaterializableLink] =
4344
ent.superTypes.collect {
4445
case UnsetLink(title, query) =>
45-
val packages = ctx.docbase.packages[Package].toMap
46+
val packages = ctx.docbase.packages
4647
val entityLink = makeEntityLink(ent, packages, Text(title), NoPosition, query).link
4748
handleEntityLink(title, entityLink, ent)
4849
}
@@ -67,13 +68,13 @@ class LinkSuperTypes extends DocMiniPhase with TypeLinker {
6768
class LinkImplicitlyAddedTypes extends DocMiniPhase with TypeLinker {
6869
override def transformDef(implicit ctx: Context) = {
6970
case df: DefImpl if df.implicitlyAddedFrom.isDefined =>
70-
val implicitlyAddedFrom = linkReference(df, df.implicitlyAddedFrom.get, ctx.docbase.packages[Package].toMap)
71+
val implicitlyAddedFrom = linkReference(df, df.implicitlyAddedFrom.get, ctx.docbase.packages)
7172
df.copy(implicitlyAddedFrom = Some(implicitlyAddedFrom))
7273
}
7374

7475
override def transformVal(implicit ctx: Context) = {
7576
case vl: ValImpl if vl.implicitlyAddedFrom.isDefined =>
76-
val implicitlyAddedFrom = linkReference(vl, vl.implicitlyAddedFrom.get, ctx.docbase.packages[Package].toMap)
77+
val implicitlyAddedFrom = linkReference(vl, vl.implicitlyAddedFrom.get, ctx.docbase.packages)
7778
vl.copy(implicitlyAddedFrom = Some(implicitlyAddedFrom))
7879
}
7980
}

‎dottydoc/src/dotty/tools/dottydoc/core/UsecasePhase.scala

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import transform.DocMiniPhase
99
import model.internal._
1010
import model.factories._
1111
import dotty.tools.dotc.core.Symbols.Symbol
12+
import util.syntax._
1213

1314
class UsecasePhase extends DocMiniPhase {
1415
private def defdefToDef(d: tpd.DefDef, sym: Symbol)(implicit ctx: Context) = {

‎dottydoc/src/dotty/tools/dottydoc/util/syntax.scala

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
package dotty.tools
2+
package dottydoc
3+
package util
4+
5+
import dotc.core.Contexts.{ Context, DocBase }
6+
import model.Package
7+
8+
object syntax {
9+
implicit class RichDocContext(val ctx: Context) extends AnyVal {
10+
def docbase: DocBase = ctx.getDocbase getOrElse {
11+
throw new IllegalStateException("DocBase must be set before running dottydoc phases")
12+
}
13+
}
14+
15+
implicit class RichDocBase(val db: DocBase) {
16+
def packages: Map[String, Package] = db.packagesAs[Package].toMap
17+
18+
def packagesMutable: collection.mutable.Map[String, Package] =
19+
db.packagesAs[Package]
20+
}
21+
}

‎dottydoc/test/BaseTest.scala

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@ package dotty.tools
22
package dottydoc
33

44
import dotc.core.Contexts
5-
import Contexts.{ Context, ContextBase, FreshContext }
5+
import Contexts.{ Context, ContextBase, FreshContext, DocContext, DocBase }
66
import dotc.util.SourceFile
77
import dotc.core.Phases.Phase
88
import dotc.typer.FrontEnd
99
import dottydoc.core.DocASTPhase
1010
import model.Package
11+
import dotty.tools.dottydoc.util.syntax._
1112

1213
trait DottyTest {
1314
dotty.tools.dotc.parsing.Scanners // initialize keywords
@@ -19,6 +20,7 @@ trait DottyTest {
1920
ctx.setSetting(ctx.settings.language, List("Scala2"))
2021
ctx.setSetting(ctx.settings.YnoInline, true)
2122
ctx.setSetting(ctx.settings.YkeepComments, true)
23+
ctx.setProperty(DocContext, new DocBase)
2224
base.initialize()(ctx)
2325
ctx
2426
}
@@ -28,7 +30,7 @@ trait DottyTest {
2830
List(new Phase {
2931
def phaseName = "assertionPhase"
3032
override def run(implicit ctx: Context): Unit =
31-
assertion(ctx.docbase.packages[Package].toMap)
33+
assertion(ctx.docbase.packages)
3234
}) :: Nil
3335

3436
override def phases =

‎dottydoc/test/UsecaseTest.scala

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import dotc.util.SourceFile
88
import model._
99
import model.internal._
1010
import model.references._
11+
import util.syntax._
1112

1213
class UsecaseTest extends DottyTest {
1314
@Test def simpleUsecase = {

‎src/dotty/tools/dotc/core/Comments.scala

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ object Comments {
155155
*/
156156
def cookedDocComment(sym: Symbol, docStr: String = "")(implicit ctx: Context): String = cookedDocComments.getOrElseUpdate(sym, {
157157
var ownComment =
158-
if (docStr.length == 0) ctx.docbase.docstring(sym).map(c => template(c.raw)).getOrElse("")
158+
if (docStr.length == 0) ctx.getDocbase.flatMap(_.docstring(sym).map(c => template(c.raw))).getOrElse("")
159159
else template(docStr)
160160
ownComment = replaceInheritDocToInheritdoc(ownComment)
161161

@@ -365,7 +365,7 @@ object Comments {
365365
def defineVariables(sym: Symbol)(implicit ctx: Context) = {
366366
val Trim = "(?s)^[\\s&&[^\n\r]]*(.*?)\\s*$".r
367367

368-
val raw = ctx.docbase.docstring(sym).map(_.raw).getOrElse("")
368+
val raw = ctx.getDocbase.flatMap(_.docstring(sym).map(_.raw)).getOrElse("")
369369
defs(sym) ++= defines(raw).map {
370370
str => {
371371
val start = skipWhitespace(str, "@define".length)
@@ -406,7 +406,7 @@ object Comments {
406406
* the position of the doc comment of the overridden version is returned instead.
407407
*/
408408
def docCommentPos(sym: Symbol)(implicit ctx: Context): Position =
409-
ctx.docbase.docstring(sym).map(_.pos).getOrElse(NoPosition)
409+
ctx.getDocbase.flatMap(_.docstring(sym).map(_.pos)).getOrElse(NoPosition)
410410

411411
/** A version which doesn't consider self types, as a temporary measure:
412412
* an infinite loop has broken out between superComment and cookedDocComment

‎src/dotty/tools/dotc/core/Contexts.scala

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ object Contexts {
6969
/** The context base at the root */
7070
val base: ContextBase
7171

72+
/** Documentation base */
73+
def getDocbase = property(DocContext)
74+
7275
/** All outer contexts, ending in `base.initialCtx` and then `NoContext` */
7376
def outersIterator = new Iterator[Context] {
7477
var current = thiscontext
@@ -537,9 +540,6 @@ object Contexts {
537540
/** The symbol loaders */
538541
val loaders = new SymbolLoaders
539542

540-
/** Documentation base */
541-
val docbase = new DocBase
542-
543543
/** The platform, initialized by `initPlatform()`. */
544544
private var _platform: Platform = _
545545

@@ -578,6 +578,7 @@ object Contexts {
578578
}
579579
}
580580

581+
val DocContext = new Key[DocBase]
581582
class DocBase {
582583
private[this] val _docstrings: mutable.Map[Symbol, Comment] =
583584
mutable.Map.empty
@@ -597,7 +598,7 @@ object Contexts {
597598
* map of `String -> AnyRef`
598599
*/
599600
private[this] val _packages: mutable.Map[String, AnyRef] = mutable.Map.empty
600-
def packages[A]: mutable.Map[String, A] = _packages.asInstanceOf[mutable.Map[String, A]]
601+
def packagesAs[A]: mutable.Map[String, A] = _packages.asInstanceOf[mutable.Map[String, A]]
601602

602603
/** Should perhaps factorize this into caches that get flushed */
603604
private var _defs: Map[Symbol, Set[Symbol]] = Map.empty

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1541,7 +1541,7 @@ object SymDenotations {
15411541

15421542
/** Enter a symbol in given `scope` without potentially replacing the old copy. */
15431543
def enterNoReplace(sym: Symbol, scope: MutableScope)(implicit ctx: Context): Unit = {
1544-
def isUsecase = sym.name.show.takeRight(4) == "$doc"
1544+
def isUsecase = ctx.property(DocContext).isDefined && sym.name.show.takeRight(4) == "$doc"
15451545
require(
15461546
(sym.denot.flagsUNSAFE is Private) ||
15471547
!(this is Frozen) ||

‎src/dotty/tools/dotc/typer/Namer.scala

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -456,7 +456,8 @@ class Namer { typer: Typer =>
456456

457457

458458
def setDocstring(sym: Symbol, tree: Tree)(implicit ctx: Context) = tree match {
459-
case t: MemberDef if t.rawComment.isDefined => ctx.docbase.addDocstring(sym, t.rawComment)
459+
case t: MemberDef if t.rawComment.isDefined =>
460+
ctx.getDocbase.foreach(_.addDocstring(sym, t.rawComment))
460461
case _ => ()
461462
}
462463

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

Lines changed: 28 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1247,7 +1247,8 @@ class Typer extends Namer with TypeAssigner with Applications with Implicits wit
12471247
val dummy = localDummy(cls, impl)
12481248
val body1 = typedStats(impl.body, dummy)(inClassContext(self1.symbol))
12491249

1250-
typedUsecases(body1.map(_.symbol), self1.symbol)(localContext(cdef, cls).setNewScope)
1250+
if (ctx.property(DocContext).isDefined)
1251+
typedUsecases(body1.map(_.symbol), self1.symbol)(localContext(cdef, cls).setNewScope)
12511252

12521253
checkNoDoubleDefs(cls)
12531254
val impl1 = cpy.Template(impl)(constr1, parents1, self1, body1)
@@ -1537,39 +1538,42 @@ class Typer extends Namer with TypeAssigner with Applications with Implicits wit
15371538
tpd.cpy.DefDef(mdef)(rhs = Inliner.bodyToInline(mdef.symbol)) ::
15381539
Inliner.removeInlineAccessors(mdef.symbol)
15391540

1540-
private def typedUsecases(syms: List[Symbol], owner: Symbol)(implicit ctx: Context): Unit = {
1541-
val relevantSyms = syms.filter(ctx.docbase.docstring(_).isDefined)
1542-
relevantSyms.foreach { sym =>
1543-
expandParentDocs(sym)
1544-
val usecases = ctx.docbase.docstring(sym).map(_.usecases).getOrElse(Nil)
1541+
private def typedUsecases(syms: List[Symbol], owner: Symbol)(implicit ctx: Context): Unit =
1542+
ctx.getDocbase.foreach { docbase =>
1543+
val relevantSyms = syms.filter(docbase.docstring(_).isDefined)
1544+
relevantSyms.foreach { sym =>
1545+
expandParentDocs(sym)
1546+
val usecases = docbase.docstring(sym).map(_.usecases).getOrElse(Nil)
15451547

1546-
usecases.foreach { usecase =>
1547-
enterSymbol(createSymbol(usecase.untpdCode))
1548+
usecases.foreach { usecase =>
1549+
enterSymbol(createSymbol(usecase.untpdCode))
15481550

1549-
typedStats(usecase.untpdCode :: Nil, owner) match {
1550-
case List(df: tpd.DefDef) => usecase.tpdCode = df
1551-
case _ => ctx.error("`@usecase` was not a valid definition", usecase.codePos)
1551+
typedStats(usecase.untpdCode :: Nil, owner) match {
1552+
case List(df: tpd.DefDef) => usecase.tpdCode = df
1553+
case _ => ctx.error("`@usecase` was not a valid definition", usecase.codePos)
1554+
}
15521555
}
15531556
}
15541557
}
1555-
}
15561558

15571559
private def expandParentDocs(sym: Symbol)(implicit ctx: Context): Unit =
1558-
ctx.docbase.docstring(sym).foreach { cmt =>
1559-
def expandDoc(owner: Symbol): Unit = if (!cmt.isExpanded) {
1560-
val tplExp = ctx.docbase.templateExpander
1561-
tplExp.defineVariables(sym)
1560+
ctx.getDocbase.foreach { docbase =>
1561+
docbase.docstring(sym).foreach { cmt =>
1562+
def expandDoc(owner: Symbol): Unit = if (!cmt.isExpanded) {
1563+
val tplExp = docbase.templateExpander
1564+
tplExp.defineVariables(sym)
15621565

1563-
val newCmt = cmt
1564-
.expand(tplExp.expandedDocComment(sym, owner, _))
1565-
.withUsecases
1566+
val newCmt = cmt
1567+
.expand(tplExp.expandedDocComment(sym, owner, _))
1568+
.withUsecases
15661569

1567-
ctx.docbase.addDocstring(sym, Some(newCmt))
1568-
}
1570+
docbase.addDocstring(sym, Some(newCmt))
1571+
}
15691572

1570-
if (sym ne NoSymbol) {
1571-
expandParentDocs(sym.owner)
1572-
expandDoc(sym.owner)
1573+
if (sym ne NoSymbol) {
1574+
expandParentDocs(sym.owner)
1575+
expandDoc(sym.owner)
1576+
}
15731577
}
15741578
}
15751579

0 commit comments

Comments
 (0)