Skip to content

Commit aabc224

Browse files
romanowskiromanowski
committed
Align scala3doc args to scala standard
We used strins settings to process lists Report warning about broken external doc early
1 parent 14d4d84 commit aabc224

File tree

6 files changed

+81
-83
lines changed

6 files changed

+81
-83
lines changed

‎project/Build.scala‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1533,9 +1533,10 @@ object Build {
15331533
val projectRoot = (ThisBuild/baseDirectory).value.toPath
15341534
val stdLibRoot = projectRoot.relativize(managedSources.toPath.normalize())
15351535
val scalaSourceLink =
1536-
s"$stdLibRoot=github://scala/scala/v${stdlibVersion(Bootstrapped)}#src/library"
1537-
val sourcesAndRevision = s"-source-links $scalaSourceLink,github://lampepfl/dotty -revision $ref -project-version $projectVersion"
1538-
val cmd = s""" -d $outDir -project "$name" $sourcesAndRevision $params $targets"""
1536+
s"$stdLibRoot=github://scala/scala/v${stdlibVersion(Bootstrapped)}#src/library"
1537+
val sourceLinks = s"-source-links:$scalaSourceLink,github://lampepfl/dotty "
1538+
val revision = s"-revision $ref -project-version $projectVersion"
1539+
val cmd = s""" -d $outDir -project "$name" $sourceLinks $revision $params $targets"""
15391540
run.in(Compile).toTask(cmd)
15401541
}
15411542

@@ -1575,12 +1576,9 @@ object Build {
15751576
classDirectory.in(Compile).value.getAbsolutePath,
15761577
"scala3doc", "scala3doc/output/self", VersionUtil.gitHash,
15771578
"-siteroot scala3doc/documentation -project-logo scala3doc/documentation/logo.svg " +
1578-
"-external-mappings " + raw".*scala.*" + "::" +
1579-
"scala3doc" + "::" +
1580-
"http://dotty.epfl.ch/api/" + ":::" +
1581-
raw".*java.*" + "::" +
1582-
"javadoc" + "::" +
1583-
"https://docs.oracle.com/javase/8/docs/api/"
1579+
"-external-mappings:" +
1580+
".*scala.*::scala3doc::http://dotty.epfl.ch/api/," +
1581+
".*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/"
15841582
)
15851583
}.value,
15861584

@@ -1615,9 +1613,7 @@ object Build {
16151613
"-skip-by-regex:.+\\.internal($|\\..+) " +
16161614
"-skip-by-regex:.+\\.impl($|\\..+) " +
16171615
"-comment-syntax wiki -siteroot scala3doc/scala3-docs -project-logo scala3doc/scala3-docs/logo.svg " +
1618-
"-external-mappings " + raw".*java.*" + "::" +
1619-
"javadoc" + "::" +
1620-
"https://docs.oracle.com/javase/8/docs/api/"
1616+
"-external-mappings:.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/"
16211617
))
16221618
}.evaluated,
16231619

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

Lines changed: 4 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ extension (r: report.type)
6969
def warn(m: String, f: File)(using CompilerContext): Unit =
7070
r.warning(createMessage(m, f, null), sourcePostionFor(f))
7171

72+
def warn(m: String, e: Throwable)(using CompilerContext): Unit =
73+
r.warning(s"$m: ${throwableToString(e)}")
74+
7275
case class NavigationNode(name: String, dri: DRI, nested: Seq[NavigationNode])
7376

7477
case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
@@ -99,51 +102,7 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
99102
sourceLinks
100103
)(using compilerContext))
101104

102-
def parseDocTool(docTool: String) = docTool match {
103-
case "scaladoc" => Some(DocumentationKind.Scaladoc)
104-
case "scala3doc" => Some(DocumentationKind.Scala3doc)
105-
case "javadoc" => Some(DocumentationKind.Javadoc)
106-
case other => None
107-
}
108-
val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = args.externalMappings.filter(_.size >= 3).flatMap { mapping =>
109-
val regexStr = mapping(0)
110-
val docTool = mapping(1)
111-
val urlStr = mapping(2)
112-
val packageListUrlStr = if mapping.size > 3 then Some(mapping(3)) else None
113-
val regex = Try(regexStr.r).toOption
114-
val url = Try(URL(urlStr)).toOption
115-
val packageListUrl = Try(packageListUrlStr.map(URL(_)))
116-
.fold(
117-
e => {
118-
logger.warn(s"Wrong packageListUrl parameter in external mapping. Found '$packageListUrlStr'. " +
119-
s"Package list url will be omitted")
120-
None},
121-
res => res
122-
)
123-
124-
val parsedDocTool = parseDocTool(docTool)
125-
val res = if regexStr.isEmpty then
126-
logger.warn(s"Wrong regex parameter in external mapping. Found '$regexStr'. Mapping will be omitted")
127-
None
128-
else if url.isEmpty then
129-
logger.warn(s"Wrong url parameter in external mapping. Found '$urlStr'. Mapping will be omitted")
130-
None
131-
else if parsedDocTool.isEmpty then
132-
logger.warn(s"Wrong doc-tool parameter in external mapping. " +
133-
s"Expected one of: 'scaladoc', 'scala3doc', 'javadoc'. Found:'$docTool'. Mapping will be omitted "
134-
)
135-
None
136-
else
137-
Some(
138-
Scala3docExternalDocumentationLink(
139-
List(regexStr.r),
140-
URL(urlStr),
141-
parsedDocTool.get,
142-
packageListUrlStr.map(URL(_))
143-
)
144-
)
145-
res
146-
}
105+
val externalDocumentationLinks = args.externalMappings
147106

148107
override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] =
149108
JNil

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
package dotty.dokka
2+
3+
import java.net.URL
4+
import scala.util.matching._
5+
import scala.util.Try
6+
7+
case class ExternalDocLink(
8+
originRegexes: List[Regex],
9+
documentationUrl: URL,
10+
kind: DocumentationKind,
11+
packageListUrl: Option[URL] = None
12+
):
13+
def withPackageList(url: URL): ExternalDocLink = copy(packageListUrl = Some(url))
14+
15+
enum DocumentationKind:
16+
case Javadoc extends DocumentationKind
17+
case Scaladoc extends DocumentationKind
18+
case Scala3doc extends DocumentationKind
19+
20+
object ExternalDocLink:
21+
def parse(mapping: String)(using CompilerContext): Option[ExternalDocLink] =
22+
def fail(msg: String) =
23+
report.warning(s"Unable to parocess external mapping $mapping. $msg")
24+
None
25+
26+
def tryParse[T](descr: String)(op: => T): Option[T] = try Some(op) catch
27+
case e: RuntimeException =>
28+
report.warn("Unable to parse $descr", e)
29+
None
30+
31+
def parsePackageList(elements: List[String]) = elements match
32+
case List(urlStr) => tryParse("packageList")(Option(URL(urlStr)))
33+
case Nil => Some(None)
34+
case other => fail(s"Provided multiple package lists: $other")
35+
36+
def doctoolByName(name: String) = name match
37+
case "javadoc" => Some(DocumentationKind.Javadoc)
38+
case "scaladoc" => Some(DocumentationKind.Scaladoc)
39+
case "scala3doc" => Some(DocumentationKind.Scala3doc)
40+
case other => fail(s"Unknown doctool: $other")
41+
42+
43+
mapping.split("::").toList match
44+
case regexStr :: docToolStr :: urlStr :: rest =>
45+
for {
46+
regex <- tryParse("regex")(regexStr.r)
47+
url <- tryParse("url")(URL(urlStr))
48+
doctool <- doctoolByName(docToolStr)
49+
packageList <- parsePackageList(rest)
50+
} yield ExternalDocLink(
51+
List(regex),
52+
url,
53+
doctool,
54+
packageList
55+
)
56+
case _ =>
57+
fail("Accepted format: `regexStr::docToolStr::urlStr[::rest]`")

‎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]] = List.empty,
68+
externalMappings: List[ExternalDocLink] = Nil,
6969
identifiersToSkip: List[String] = Nil,
7070
regexesToSkip: List[String] = Nil,
7171
)

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

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,25 +25,28 @@ class Scala3docArgs extends SettingGroup with CommonScalaSettings:
2525
sourcepath, sourceroot
2626
)
2727

28-
val sourceLinks: Setting[String] =
29-
StringSetting("-source-links", "sources", SourceLinks.usage, "")
28+
val sourceLinks: Setting[List[String]] =
29+
MultiStringSetting("-source-links", "sources", SourceLinks.usage)
3030

3131
val syntax: Setting[String] =
3232
StringSetting("-comment-syntax", "syntax", "Syntax of the comment used", "")
3333

3434
val revision: Setting[String] =
3535
StringSetting("-revision", "revision", "Revision (branch or ref) used to build project project", "")
3636

37-
val externalDocumentationMappings: Setting[String] =
38-
StringSetting("-external-mappings", "external-mappings", "Mapping between regex matching class file and external documentation", "")
37+
val externalDocumentationMappings: Setting[List[String]] =
38+
MultiStringSetting("-external-mappings", "external-mappings",
39+
"Mapping between regexes matching classpath entries and external documentation. " +
40+
"'regex::[scaladoc|scala3doc|javadoc]::path' syntax is used")
3941

4042
val skipById: Setting[List[String]] =
4143
MultiStringSetting("-skip-by-id", "package or class identifier", "Identifiers of packages or top-level classes to skip when generating documentation")
4244

4345
val skipByRegex: Setting[List[String]] =
4446
MultiStringSetting("-skip-by-regex", "regex", "Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation")
4547

46-
def scala3docSpecificSettings: Set[Setting[_]] = Set(sourceLinks, syntax, revision, externalDocumentationMappings, skipById, skipByRegex)
48+
def scala3docSpecificSettings: Set[Setting[_]] =
49+
Set(sourceLinks, syntax, revision, externalDocumentationMappings, skipById, skipByRegex)
4750

4851
object Scala3docArgs:
4952
def extract(args: List[String], rootCtx: CompilerContext):(Scala3doc.Args, CompilerContext) =
@@ -104,7 +107,8 @@ object Scala3docArgs:
104107
CommentSyntax.default
105108
}
106109
}
107-
val externalMappings = externalDocumentationMappings.get.split(":::").map(_.split("::").toList).toList
110+
val externalMappings =
111+
externalDocumentationMappings.get.flatMap(ExternalDocLink.parse)
108112

109113
unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
110114
report.warning(s"Setting ${s.name} is currently not supported.")
@@ -124,7 +128,7 @@ object Scala3docArgs:
124128
projectVersion.nonDefault,
125129
projectLogo.nonDefault,
126130
parseSyntax,
127-
sourceLinks.nonDefault.fold(Nil)(_.split(",").toList),
131+
sourceLinks.get,
128132
revision.nonDefault,
129133
externalMappings,
130134
skipById.get,

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

Lines changed: 0 additions & 18 deletions
This file was deleted.

0 commit comments

Comments
 (0)