Skip to content

Commit 7921504

Browse files
pikinier20pikinier20
committed
Change usage of DRI. Change pages structure to more standarized. Minor fixes to external location mechanism.
1 parent 77f72c4 commit 7921504

16 files changed

+124
-78
lines changed

‎project/Build.scala

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1565,7 +1565,17 @@ object Build {
15651565
generateDocumentation(
15661566
classDirectory.in(Compile).value.getAbsolutePath,
15671567
"scala3doc", "scala3doc/output/self", VersionUtil.gitHash,
1568-
"-siteroot scala3doc/documentation -project-logo scala3doc/documentation/logo.svg")
1568+
"-siteroot scala3doc/documentation -project-logo scala3doc/documentation/logo.svg " +
1569+
"-external-mappings " + raw".*scala\/quoted.*" + "::" +
1570+
"scala3doc" + "::" +
1571+
"http://dotty.epfl.ch/api/" + ":::" +
1572+
raw".*java.*" + "::" +
1573+
"javadoc" + "::" +
1574+
"https://docs.oracle.com/javase/8/docs/api/" + ":::" +
1575+
raw".*scala.*" + "::" +
1576+
"scaladoc" + "::" +
1577+
"https://www.scala-lang.org/api/current/"
1578+
)
15691579
}.value,
15701580

15711581
generateScala3Documentation := Def.inputTaskDyn {
@@ -1589,7 +1599,14 @@ object Build {
15891599
IO.write(dest / "CNAME", "dotty.epfl.ch")
15901600
}.dependsOn(generateDocumentation(
15911601
roots, "Scala 3", dest.getAbsolutePath, "master",
1592-
"-comment-syntax wiki -siteroot scala3doc/scala3-docs -project-logo scala3doc/scala3-docs/logo.svg"))
1602+
"-comment-syntax wiki -siteroot scala3doc/scala3-docs -project-logo scala3doc/scala3-docs/logo.svg " +
1603+
"-external-mappings " + raw".*java.*" + "::" +
1604+
"javadoc" + "::" +
1605+
"https://docs.oracle.com/javase/8/docs/api/" + ":::" +
1606+
raw".*scala.*" + "::" +
1607+
"scaladoc" + "::" +
1608+
"https://www.scala-lang.org/api/current/"
1609+
))
15931610
}.evaluated,
15941611

15951612
generateTestcasesDocumentation := Def.taskDyn {

‎scala3doc/src/dotty/dokka/DocContext.scala

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -141,24 +141,6 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
141141
res
142142
}
143143

144-
//val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = List(
145-
// Scala3docExternalDocumentationLink(
146-
// List(raw".*scala\/quoted.*".r),
147-
// new URL("http://127.0.0.1:5500/scala3doc/output/scala3/"),
148-
// DocumentationKind.Scala3doc
149-
// ).withPackageList(new URL("http://127.0.0.1:5500/scala3doc/output/scala3/-scala%203/package-list")),
150-
// Scala3docExternalDocumentationLink(
151-
// List(raw".*java.*".r),
152-
// new URL("https://docs.oracle.com/javase/8/docs/api/"),
153-
// DocumentationKind.Javadoc
154-
// ).withPackageList(new URL("https://docs.oracle.com/javase/8/docs/api/package-list")),
155-
// Scala3docExternalDocumentationLink(
156-
// List(raw".*scala.*".r),
157-
// new URL("https://www.scala-lang.org/api/current/"),
158-
// DocumentationKind.Scaladoc
159-
// )
160-
//)
161-
162144
override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] =
163145
JList()
164146

‎scala3doc/src/dotty/dokka/Scala3doc.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ object Scala3doc:
6565
defaultSyntax: CommentSyntax = CommentSyntax.Markdown,
6666
sourceLinks: List[String] = Nil,
6767
revision: Option[String] = None,
68-
externalMappings: List[List[String]]
68+
externalMappings: List[List[String]] = List.empty
6969
)
7070

7171
def run(args: Array[String], rootContext: CompilerContext): Reporter =

‎scala3doc/src/dotty/dokka/compat.scala

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,6 @@ import java.util.stream.Collectors
1414
import org.jetbrains.dokka.plugability._
1515
import kotlin.jvm.JvmClassMappingKt.getKotlinClass
1616

17-
def mkDRI(packageName: String = null, extra: String = null) = new DRI(packageName, null, null, PointingToDeclaration.INSTANCE, extra)
18-
1917
val U: kotlin.Unit = kotlin.Unit.INSTANCE
2018

2119
def JList[T](e: T*): JList[T] = e.asJava

‎scala3doc/src/dotty/dokka/location/ScalaExternalLocationProvider.scala

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import org.jetbrains.dokka.base.resolvers.anchors._
88
import org.jetbrains.dokka.links.DRI
99
import org.jetbrains.dokka.model.DisplaySourceSet
1010
import org.jetbrains.dokka.pages.RootPageNode
11+
import dotty.dokka.model.api._
1112
import org.jetbrains.dokka.plugability._
1213
import collection.JavaConverters._
1314
import java.util.{Set => JSet}
@@ -34,20 +35,20 @@ class ScalaExternalLocationProvider(
3435
}
3536

3637
private def constructPathForJavadoc(dri: DRI): String = {
37-
val packagePrefix = dri.getPackageName.replace(".","/")
38-
val origin = originRegex.findFirstIn(dri.getExtra)
39-
val className = origin match {
40-
case Some(path) =>
41-
path.split("/").last.stripSuffix(".class")
42-
case None => dri.getClassNames
43-
}
44-
getDocURL + packagePrefix + "/" + className + extension
38+
val location = "\\$+".r.replaceAllIn(dri.location.replace(".","/"), _ => ".")
39+
val origin = originRegex.findFirstIn(dri.extra)
40+
val anchor = dri.anchor
41+
getDocURL + location + extension + anchor.fold("")(a => s"#$a")
4542
}
4643

4744
private def constructPathForScaladoc(dri: DRI): String = {
48-
val packagePrefix = dri.getPackageName.replace(".","/")
49-
val className = dri.getClassNames
50-
getDocURL + packagePrefix + "/" + className + extension
45+
val location = dri.location.replace(".","/")
46+
val anchor = dri.anchor
47+
getDocURL + location + extension + anchor.fold("")(a => s"#$a")
5148
}
5249

53-
private def constructPathForScala3doc(dri: DRI): String = super.constructPath(dri)
50+
private def constructPathForScala3doc(dri: DRI): String = {
51+
val location = dri.location.replace(".","/")
52+
val anchor = dri.anchor
53+
getDocURL + location + anchor.fold(extension)(a => s"/$a$extension")
54+
}

‎scala3doc/src/dotty/dokka/model/api/api.scala

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import collection.JavaConverters._
88
import org.jetbrains.dokka.model.doc._
99
import org.jetbrains.dokka.model.properties._
1010
import org.jetbrains.dokka.pages._
11+
import org.jetbrains.dokka.links._
1112

1213
enum Visibility(val name: String):
1314
case Unrestricted extends Visibility("")
@@ -149,12 +150,31 @@ extension (module: DModule):
149150
def driMap: Map[DRI, Member] = ModuleExtension.getFrom(module).fold(Map.empty)(_.driMap)
150151

151152
extension (dri: DRI):
152-
def withNoOrigin = DRI(
153-
dri.getPackageName,
154-
dri.getClassNames,
155-
dri.getCallable,
156-
dri.getTarget,
157-
Option(dri.getExtra).fold(null)(e => raw"\[origin:(.*)\]".r.replaceAllIn(e, ""))
153+
def withNoOrigin = dri._copy(
154+
extra = Option(dri.getExtra).fold(null)(e => raw"\[origin:(.*)\]".r.replaceAllIn(e, ""))
158155
)
159156

157+
def location: String = dri.getPackageName
158+
159+
def anchor: Option[String] = Option(dri.getClassNames).filterNot(_.isEmpty)
160+
161+
def extra: String = dri.getExtra
162+
163+
def target: DriTarget = dri.getTarget
164+
165+
def _copy(
166+
location: String = dri.location,
167+
anchor: Option[String] = dri.anchor,
168+
target: DriTarget = dri.target,
169+
extra: String = dri.extra
170+
) = new DRI(location, anchor.getOrElse(""), null, target, extra)
171+
172+
object DRI:
173+
def apply(
174+
location: String = "",
175+
anchor: Option[String] = None,
176+
target: DriTarget = PointingToDeclaration.INSTANCE,
177+
extra: String = ""
178+
) = new DRI(location, anchor.getOrElse(""), null, target, extra)
179+
160180
case class TastyDocumentableSource(val path: String, val lineNumber: Int)

‎scala3doc/src/dotty/dokka/site/SitePagesCreator.scala

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ import org.jetbrains.dokka.pages._
1010

1111
import scala.collection.JavaConverters._
1212

13+
import dotty.dokka.model.api._
14+
1315
class SitePagesCreator(using ctx: DocContext) extends BaseStaticSiteProcessor:
1416
private def mkRootPage(input: RootPageNode, children: List[PageNode]): AContentPage =
1517
input match
@@ -44,7 +46,7 @@ class SitePagesCreator(using ctx: DocContext) extends BaseStaticSiteProcessor:
4446
val msg = s"ERROR: Multiple index pages for doc found ${indexes.map(_.template.file)}"
4547
report.error(msg)
4648

47-
def emptyContent = ctx.asContent(Text(), mkDRI(extra = "root_content")).get(0)
49+
def emptyContent = ctx.asContent(Text(), DRI(extra = "root_content")).get(0)
4850

4951
val root = ctx.indexPage().toList.map(_.copy(getDri = JSet(docsRootDRI)))
5052
val docsRoot = AContentPage(

‎scala3doc/src/dotty/dokka/site/StaticSiteContext.scala

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ import util.Try
2020

2121
import scala.collection.JavaConverters._
2222

23+
import dotty.dokka.model.api._
24+
2325
class StaticSiteContext(
2426
val root: File,
2527
sourceSets: Set[SourceSetWrapper],
@@ -166,7 +168,7 @@ class StaticSiteContext(
166168
}.toOption
167169
pathsDri.getOrElse(memberLinkResolver(link).toList)
168170

169-
def driFor(dest: Path): DRI = mkDRI(s"_.${root.toPath.relativize(dest)}")
171+
def driFor(dest: Path): DRI = DRI(location = s"_.${root.toPath.relativize(dest)}")
170172

171173
def relativePath(myTemplate: LoadedTemplate) = root.toPath.relativize(myTemplate.file.toPath)
172174

‎scala3doc/src/dotty/dokka/site/StaticSiteLocationProvider.scala

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import org.jetbrains.dokka.pages.ContentPage
55
import org.jetbrains.dokka.pages.PageNode
66
import org.jetbrains.dokka.pages.RootPageNode
77
import org.jetbrains.dokka.pages.ModulePage
8+
import org.jetbrains.dokka.model.DPackage
89
import org.jetbrains.dokka.plugability.DokkaContext
910
import org.jetbrains.dokka.base.resolvers.external._
1011
import org.jetbrains.dokka.base.resolvers.shared._
@@ -16,6 +17,7 @@ import scala.collection.JavaConverters._
1617
import java.nio.file.Paths
1718
import java.nio.file.Path
1819
import scala.util.matching._
20+
import dotty.dokka.model.api._
1921

2022
class StaticSiteLocationProviderFactory(using ctx: DokkaContext) extends LocationProviderFactory:
2123
override def getLocationProvider(pageNode: RootPageNode): LocationProvider =
@@ -69,6 +71,13 @@ class StaticSiteLocationProvider(pageNode: RootPageNode)(using ctx: DokkaContext
6971

7072
case _: ModulePage if summon[DocContext].staticSiteContext.isEmpty =>
7173
JList("index")
74+
case page: ContentPage if page.getDocumentable != null =>
75+
(
76+
List("api") ++
77+
page.getDocumentable.getDri.location.split(Array('.')).toList ++
78+
(if(page.getDocumentable.isInstanceOf[DPackage]) then List("index") else List.empty) ++
79+
page.getDocumentable.getDri.anchor
80+
).asJava
7281
case _ =>
7382
jpath
7483

@@ -116,7 +125,7 @@ class StaticSiteLocationProvider(pageNode: RootPageNode)(using ctx: DokkaContext
116125

117126
override def getExternalLocation(dri: DRI, sourceSets: JSet[DisplaySourceSet]): String =
118127
val regex = raw"\[origin:(.*)\]".r
119-
val origin = regex.findFirstIn(Option(dri.getExtra).getOrElse(""))
128+
val origin = regex.findFirstIn(Option(dri.extra).getOrElse(""))
120129
origin match {
121130
case Some(path) => externalLocationProviders.find { (regexes, provider) =>
122131
regexes.exists(r => r.matches(path))

‎scala3doc/src/dotty/dokka/site/common.scala

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package site
33

44
import java.io.File
55
import java.nio.file.Files
6+
import dotty.dokka.model.api._
67

78
import com.vladsch.flexmark.ext.anchorlink.AnchorLinkExtension
89
import com.vladsch.flexmark.ext.autolink.AutolinkExtension
@@ -22,9 +23,9 @@ import org.jetbrains.dokka.pages._
2223

2324
import scala.collection.JavaConverters._
2425

25-
val docsRootDRI: DRI = mkDRI("_.index.md")
26-
val docsDRI: DRI = mkDRI("_.docs/index.md")
27-
val apiPageDRI: DRI = mkDRI(packageName = "api", extra = "__api__")
26+
val docsRootDRI: DRI = DRI(location = "_.index.md")
27+
val docsDRI: DRI = DRI(location = "_.docs/index.md")
28+
val apiPageDRI: DRI = DRI(location = "api", extra = "__api__")
2829

2930
val defaultMarkdownOptions: DataHolder =
3031
new MutableDataSet()

‎scala3doc/src/dotty/dokka/tasty/PackageSupport.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ trait PackageSupport:
3434
parseClasslike(pckObj) match {
3535
case clazz: DClass =>
3636
DPackage(
37-
new DRI(pckObj.symbol.dri.getPackageName, null, null, PointingToDeclaration.INSTANCE, null),
37+
new DRI(pckObj.symbol.packageName, null, null, PointingToDeclaration.INSTANCE, null),
3838
clazz.getFunctions,
3939
clazz.getProperties,
4040
JList(),

‎scala3doc/src/dotty/dokka/tasty/SymOps.scala

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,22 @@ class SymOps[Q <: Quotes](val q: Q):
1515

1616
given Q = q
1717
extension (sym: Symbol):
18-
def packageName: String =
18+
def packageName: String = (
1919
if (sym.isPackageDef) sym.fullName
2020
else sym.maybeOwner.packageName
21+
)
2122

22-
def topLevelEntryName: Option[String] = if (sym.isPackageDef) None else
23-
if (sym.owner.isPackageDef) Some(sym.name) else sym.owner.topLevelEntryName
23+
def className: Option[String] =
24+
if (sym.isClassDef && !sym.flags.is(Flags.Package)) Some(
25+
Some(sym.maybeOwner).filter(s => s.exists).flatMap(_.className).fold("")(cn => cn + "$") + sym.name
26+
)
27+
else if (sym.isPackageDef) None
28+
else sym.maybeOwner.className
29+
30+
def anchor: Option[String] =
31+
if (!sym.isClassDef && !sym.isPackageDef) Some(sym.name)
32+
else None
33+
//TODO: Retrieve string that will match scaladoc anchors
2434

2535
def getVisibility(): Visibility =
2636
import VisibilityScope._
@@ -115,11 +125,10 @@ class SymOps[Q <: Quotes](val q: Q):
115125
val csym = sym.asInstanceOf[dotc.core.Symbols.Symbol]
116126
Option(csym.associatedFile).map(_.path).fold("")(p => s"[origin:$p]")
117127
}
118-
119-
new DRI(
120-
sym.packageName,
121-
sym.topLevelEntryName.orNull, // TODO do we need any of this fields?
122-
method.map(s => new org.jetbrains.dokka.links.Callable(s.name, null, JList())).orNull,
128+
DRI(
129+
sym.className.fold(sym.packageName)(cn => s"${sym.packageName}.${cn}"),
130+
sym.anchor.getOrElse(""), // TODO do we need any of this fields?
131+
null,
123132
pointsTo,
124133
// sym.show returns the same signature for def << = 1 and def >> = 2.
125134
// For some reason it contains `$$$` instrad of symbol name

‎scala3doc/src/dotty/dokka/tasty/TastyParser.scala

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import dotty.dokka.model.api.withNewMembers
2020
import dotty.dokka.tasty.comments.MemberLookup
2121
import dotty.dokka.tasty.comments.QueryParser
2222
import scala.util.Try
23+
import dotty.dokka.model.api._
2324

2425
/** Responsible for collectively inspecting all the Tasty files we're interested in.
2526
*
@@ -62,26 +63,30 @@ case class DokkaTastyInspector(parser: Parser)(using ctx: DocContext) extends Do
6263
.map((dri, pckgs) =>
6364
pckgs.reduce(_.mergeWith(_))
6465
)
66+
.toList
67+
.sortBy( pckg => pckg.dri.location.size )
68+
.reverse
6569

66-
val byPackage = all.filter(_.getDri != null).groupBy(_.getDri().getPackageName())
67-
byPackage.map {
68-
case (pck, entries) => {
69-
val found = packages.find(d => d.getName == pck)
70-
.map( f =>
71-
new DPackage(
72-
f.getDri,
73-
f.getFunctions,
74-
f.getProperties,
75-
JList(), // TODO add support for other things like type or package object entries
76-
JList(),
77-
f.getDocumentation,
78-
null,
79-
JSet(ctx.sourceSet),
80-
f.getExtra
81-
).withNewMembers(entries.filterNot(_.isInstanceOf[DPackage]).toList).asInstanceOf[DPackage]
82-
)
83-
found.getOrElse(throw IllegalStateException("No package for entries found"))
84-
}
70+
71+
val byPackage = all.filter(_.dri != null).groupBy( p =>
72+
packages.find(d => p.dri.location.contains(d.dri.location)).getOrElse(throw IllegalStateException("No package for entries found"))
73+
)
74+
75+
byPackage
76+
.map {
77+
case (f, entries) => {
78+
new DPackage(
79+
f.getDri,
80+
f.getFunctions,
81+
f.getProperties,
82+
JList(), // TODO add support for other things like type or package object entries
83+
JList(),
84+
f.getDocumentation,
85+
null,
86+
JSet(ctx.sourceSet),
87+
f.getExtra
88+
).withNewMembers(entries.filterNot(_.isInstanceOf[DPackage]).toList).asInstanceOf[DPackage]
89+
}
8590
}.toList
8691

8792
extension (self: DPackage) def mergeWith(other: DPackage): DPackage =

‎scala3doc/src/dotty/dokka/translators/ScalaSignatureUtils.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ trait SignatureBuilder extends ScalaSignatureUtils {
4747
d.annotations.foldLeft(this){ (bdr, annotation) => bdr.buildAnnotation(annotation) }
4848

4949
private def buildAnnotation(a: Annotation): SignatureBuilder =
50-
text("@").driLink(a.dri.getClassNames, a.dri).buildAnnotationParams(a).text(" ")
50+
text("@").driLink(a.dri.location.split('.').last, a.dri).buildAnnotationParams(a).text(" ")
5151

5252
private def buildAnnotationParams(a: Annotation): SignatureBuilder =
5353
if !a.params.isEmpty then

‎scala3doc/src/dotty/renderers/html.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ object HTML:
3131
case a: AppliedTag =>
3232
sb.append(a)
3333
case s: String =>
34-
sb.append(s.escapeReservedTokens)
34+
sb.append(s.escapeReservedTokens)
3535
}
3636
}
3737
sb.append(s"</$name>")

‎scala3doc/test/dotty/dokka/testUtils.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ class TestReporter extends ConsoleReporter:
5353
def testArgs(files: Seq[File] = Nil, dest: File = new File("notUsed")) = Scala3doc.Args(
5454
name = "Test Project Name",
5555
output = dest,
56-
tastyFiles = files
56+
tastyFiles = files,
5757
)
5858

5959
def testContext = (new ContextBase).initialCtx.fresh.setReporter(new TestReporter)

0 commit comments

Comments
 (0)