Skip to content

Commit 312517d

Browse files
romanowskiromanowski
committed
Fixes for rendering link to documentation
Do not fail on missing link but display a warning.
1 parent 3af2320 commit 312517d

File tree

8 files changed

+77
-49
lines changed

8 files changed

+77
-49
lines changed

‎project/Build.scala

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1516,7 +1516,7 @@ object Build {
15161516
else generateDocumentation(roots, "Scala 3", "scala3", "-p scala3doc/scala3-docs --projectLogo scala3doc/scala3-docs/logo.svg --revision master")
15171517
}.value,
15181518
generateTestcasesDocumentation := Def.taskDyn {
1519-
generateDocumentation(Build.testcasesOutputDir.in(Test).value, "Scala3doc testcases", "testcases")
1519+
generateDocumentation(Build.testcasesOutputDir.in(Test).value, "Scala3doc testcases", "testcases", "--revision master")
15201520
}.value,
15211521
buildInfoKeys in Test := Seq[BuildInfoKey](
15221522
Build.testcasesOutputDir.in(Test),

‎scala3doc-testcases/src/tests/links.scala

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
package tests.links
2+
3+
object AnObject:
4+
def method(a: Int): Int
5+
= 123 + a
6+
val field =
7+
123
8+
9+
/**
10+
* Broken link, that should result a warning not break compilation
11+
* [[tests.links.AnObject]]
12+
13+
*/
14+
class LinksTest:
15+
def verifyIfLinksTestIsGenerated(b: Int): Int
16+
= 123

‎scala3doc/documentation/docs/design.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Design of scala3doc
2+
3+
**BEWARE this is not complete documentation yet but rather a draft mainly to test linking from static site to code**
4+
5+
## Interface
6+
7+
Scala3doc is intednted to be use with sbt as well as from commend line or from other buildtools. The main entry point to processing is [Main](dotty.dokka.Main$) class with [[dotty.dokka.Main$.main]].

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ case class SourceLinks(links: Seq[SourceLink], projectRoot: Path):
9090
object SourceLinks:
9191

9292
val usage =
93-
"""Source links provide a mapping between file in documentation and code repositry (usual)." +
93+
"""Source links provide a mapping between file in documentation and code repositry.
9494
|Accepted formats:
9595
|<sub-path>=<source-link>
9696
|<source-link>

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import com.vladsch.flexmark.ext.tables.TablesExtension
1313
import com.vladsch.flexmark.ext.yaml.front.matter.{AbstractYamlFrontMatterVisitor, YamlFrontMatterExtension}
1414
import com.vladsch.flexmark.parser.{Parser, ParserEmulationProfile}
1515
import com.vladsch.flexmark.util.options.{DataHolder, MutableDataSet}
16+
import com.vladsch.flexmark.ext.wikilink.WikiLinkExtension
1617
import org.jetbrains.dokka.model.doc.Text
1718

1819
import scala.collection.JavaConverters._
@@ -24,7 +25,6 @@ val apiPageDRI: DRI = mkDRI(packageName = "api", extra = "__api__")
2425
val defaultMarkdownOptions: DataHolder =
2526
new MutableDataSet()
2627
.setFrom(ParserEmulationProfile.KRAMDOWN.getOptions)
27-
.set(Parser.INDENTED_CODE_BLOCK_PARSER, false)
2828
.set(AnchorLinkExtension.ANCHORLINKS_WRAP_TEXT, false)
2929
.set(AnchorLinkExtension.ANCHORLINKS_ANCHOR_CLASS, "anchor")
3030
.set(EmojiExtension.ROOT_IMAGE_PATH, "https://github.global.ssl.fastly.net/images/icons/emoji/")
@@ -35,7 +35,8 @@ val defaultMarkdownOptions: DataHolder =
3535
AnchorLinkExtension.create(),
3636
EmojiExtension.create(),
3737
YamlFrontMatterExtension.create(),
38-
StrikethroughExtension.create()
38+
StrikethroughExtension.create(),
39+
WikiLinkExtension.create()
3940
))
4041

4142
def emptyTemplate(file: File, title: String): TemplateFile = TemplateFile(

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

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -111,10 +111,7 @@ trait DokkaBaseTastyInspector:
111111
MemberLookup.lookupOpt(q, None).map{ case (sym, _) => sym.dri}
112112
)
113113

114-
config.staticSiteContext.foreach { p =>
115-
val previous = p.memberLinkResolver
116-
p.memberLinkResolver = link => previous(link).orElse(driFor(link))
117-
}
114+
config.staticSiteContext.foreach(_.memberLinkResolver = driFor)
118115
topLevels ++= parser.parseRootTree(root.asInstanceOf[parser.qctx.reflect.Tree])
119116

120117
def result(): List[DPackage] =

‎scala3doc/src/dotty/dokka/tasty/comments/MemberLookup.scala

Lines changed: 46 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -12,47 +12,52 @@ trait MemberLookup {
1212
def lookupOpt(using QuoteContext)(
1313
query: Query,
1414
ownerOpt: Option[qctx.reflect.Symbol],
15-
): Option[(qctx.reflect.Symbol, String)] = {
16-
import qctx.reflect._
17-
18-
def nearestClass(sym: Symbol): Symbol =
19-
if sym.isClassDef then sym else nearestClass(sym.owner)
20-
21-
def nearestPackage(sym: Symbol): Symbol =
22-
if sym.flags.is(Flags.Package) then sym else nearestPackage(sym.owner)
23-
24-
def nearestMembered(sym: Symbol): Symbol =
25-
if sym.isClassDef || sym.flags.is(Flags.Package) then sym else nearestMembered(sym.owner)
26-
27-
val res =
28-
ownerOpt match {
29-
case Some(owner) =>
30-
val nearest = nearestMembered(owner)
31-
val nearestCls = nearestClass(owner)
32-
val nearestPkg = nearestPackage(owner)
33-
query match {
34-
case Query.StrictMemberId(id) => localLookup(id, nearest).map(_ -> id)
35-
case Query.Id(id) =>
36-
(localLookup(id, nearest) orElse localLookup(id, nearestPkg)).map(_ -> id)
37-
case Query.QualifiedId(Query.Qual.This, _, rest) =>
38-
downwardLookup(rest.asList, nearestCls).map(_ -> rest.join)
39-
case Query.QualifiedId(Query.Qual.Package, _, rest) =>
40-
downwardLookup(rest.asList, nearestPkg).map(_ -> rest.join)
41-
case Query.QualifiedId(Query.Qual.Id(id), _, rest) if id == nearestCls.name =>
42-
downwardLookup(rest.asList, nearestCls).map(_ -> rest.join)
43-
case Query.QualifiedId(Query.Qual.Id(id), _, rest) if id == nearestPkg.name =>
44-
downwardLookup(rest.asList, nearestPkg).map(_ -> rest.join)
45-
case query: Query.QualifiedId => downwardLookup(query.asList, defn.RootPackage).map(_ -> query.join)
46-
}
47-
48-
case None =>
49-
downwardLookup(query.asList, defn.RootPackage).map(_ -> query.join)
50-
}
51-
52-
// println(s"looked up `$query` in ${owner.show}[${owner.flags.show}] as ${res.map(_.show)}")
53-
54-
res
55-
}
15+
): Option[(qctx.reflect.Symbol, String)] =
16+
try
17+
import qctx.reflect._
18+
19+
def nearestClass(sym: Symbol): Symbol =
20+
if sym.isClassDef then sym else nearestClass(sym.owner)
21+
22+
def nearestPackage(sym: Symbol): Symbol =
23+
if sym.flags.is(Flags.Package) then sym else nearestPackage(sym.owner)
24+
25+
def nearestMembered(sym: Symbol): Symbol =
26+
if sym.isClassDef || sym.flags.is(Flags.Package) then sym else nearestMembered(sym.owner)
27+
28+
val res =
29+
ownerOpt match {
30+
case Some(owner) =>
31+
val nearest = nearestMembered(owner)
32+
val nearestCls = nearestClass(owner)
33+
val nearestPkg = nearestPackage(owner)
34+
query match {
35+
case Query.StrictMemberId(id) => localLookup(id, nearest).map(_ -> id)
36+
case Query.Id(id) =>
37+
(localLookup(id, nearest) orElse localLookup(id, nearestPkg)).map(_ -> id)
38+
case Query.QualifiedId(Query.Qual.This, _, rest) =>
39+
downwardLookup(rest.asList, nearestCls).map(_ -> rest.join)
40+
case Query.QualifiedId(Query.Qual.Package, _, rest) =>
41+
downwardLookup(rest.asList, nearestPkg).map(_ -> rest.join)
42+
case Query.QualifiedId(Query.Qual.Id(id), _, rest) if id == nearestCls.name =>
43+
downwardLookup(rest.asList, nearestCls).map(_ -> rest.join)
44+
case Query.QualifiedId(Query.Qual.Id(id), _, rest) if id == nearestPkg.name =>
45+
downwardLookup(rest.asList, nearestPkg).map(_ -> rest.join)
46+
case query: Query.QualifiedId => downwardLookup(query.asList, defn.RootPackage).map(_ -> query.join)
47+
}
48+
49+
case None =>
50+
downwardLookup(query.asList, defn.RootPackage).map(_ -> query.join)
51+
}
52+
53+
// println(s"looked up `$query` in ${owner.show}[${owner.flags.show}] as ${res.map(_.show)}")
54+
55+
res
56+
catch
57+
case e: Exception =>
58+
// TODO (https://github.com/lampepfl/scala3doc/issues/238): proper reporting
59+
println(s"[WARN] Unable to find a link for ${query} ${ownerOpt.fold("")(o => "in " + o.name)}")
60+
None
5661

5762
private def hackMembersOf(using QuoteContext)(rsym: qctx.reflect.Symbol) = {
5863
import qctx.reflect._

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,3 +58,5 @@ class InheritedMembers extends SignatureTest("inheritedMembers2", SignatureTest.
5858
sourceFiles = List("inheritedMembers1", "inheritedMembers2"))
5959

6060
class ComplexNames extends SignatureTest("complexNames", Seq("def"))
61+
62+
class WrongDocumentationLinks extends SignatureTest("links", Seq("def"))

0 commit comments

Comments
 (0)