Skip to content

Commit 77f72c4

Browse files
pikinier20pikinier20
committed
Add cli parameter to handle external documentation mappings
1 parent e95933b commit 77f72c4

File tree

5 files changed

+75
-22
lines changed

5 files changed

+75
-22
lines changed

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

Lines changed: 64 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import java.io.ByteArrayOutputStream
1919
import java.io.PrintStream
2020
import scala.io.Codec
2121
import java.net.URL
22+
import scala.util.Try
2223

2324
type CompilerContext = dotty.tools.dotc.core.Contexts.Context
2425

@@ -94,23 +95,69 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
9495
sourceLinks
9596
)(using compilerContext))
9697

97-
val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = List(
98-
Scala3docExternalDocumentationLink(
99-
List(raw".*scala\/quoted.*".r),
100-
new URL("http://127.0.0.1:5500/scala3doc/output/scala3/"),
101-
DocumentationKind.Scala3doc
102-
).withPackageList(new URL("http://127.0.0.1:5500/scala3doc/output/scala3/-scala%203/package-list")),
103-
Scala3docExternalDocumentationLink(
104-
List(raw".*java.*".r),
105-
new URL("https://docs.oracle.com/javase/8/docs/api/"),
106-
DocumentationKind.Javadoc
107-
).withPackageList(new URL("https://docs.oracle.com/javase/8/docs/api/package-list")),
108-
Scala3docExternalDocumentationLink(
109-
List(raw".*scala.*".r),
110-
new URL("https://www.scala-lang.org/api/current/"),
111-
DocumentationKind.Scaladoc
112-
)
113-
)
98+
def parseDocTool(docTool: String) = docTool match {
99+
case "scaladoc" => Some(DocumentationKind.Scaladoc)
100+
case "scala3doc" => Some(DocumentationKind.Scala3doc)
101+
case "javadoc" => Some(DocumentationKind.Javadoc)
102+
case other => None
103+
}
104+
val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = args.externalMappings.filter(_.size >= 3).flatMap { mapping =>
105+
val regexStr = mapping(0)
106+
val docTool = mapping(1)
107+
val urlStr = mapping(2)
108+
val packageListUrlStr = if mapping.size > 3 then Some(mapping(3)) else None
109+
val regex = Try(regexStr.r).toOption
110+
val url = Try(URL(urlStr)).toOption
111+
val packageListUrl = Try(packageListUrlStr.map(URL(_)))
112+
.fold(
113+
e => {
114+
logger.warn(s"Wrong packageListUrl parameter in external mapping. Found '$packageListUrlStr'. " +
115+
s"Package list url will be omitted")
116+
None},
117+
res => res
118+
)
119+
120+
val parsedDocTool = parseDocTool(docTool)
121+
val res = if regexStr.isEmpty then
122+
logger.warn(s"Wrong regex parameter in external mapping. Found '$regexStr'. Mapping will be omitted")
123+
None
124+
else if url.isEmpty then
125+
logger.warn(s"Wrong url parameter in external mapping. Found '$urlStr'. Mapping will be omitted")
126+
None
127+
else if parsedDocTool.isEmpty then
128+
logger.warn(s"Wrong doc-tool parameter in external mapping. " +
129+
s"Expected one of: 'scaladoc', 'scala3doc', 'javadoc'. Found:'$docTool'. Mapping will be omitted "
130+
)
131+
None
132+
else
133+
Some(
134+
Scala3docExternalDocumentationLink(
135+
List(regexStr.r),
136+
URL(urlStr),
137+
parsedDocTool.get,
138+
packageListUrlStr.map(URL(_))
139+
)
140+
)
141+
res
142+
}
143+
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+
//)
114161

115162
override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] =
116163
JList()

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ class DottyDokkaPlugin extends DokkaJavaPlugin:
182182

183183
val scalaExternalLocationProviderFactory = extend(
184184
_.extensionPoint(dokkaBase.getExternalLocationProviderFactory)
185-
.fromRecipe{ case c as given DokkaContext => new ScalaExternalLocationProviderFactory }
185+
.fromRecipe{ case c @ given DokkaContext => new ScalaExternalLocationProviderFactory }
186186
.overrideExtension(dokkaBase.getDokkaLocationProvider)
187187
)
188188

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,8 @@ object Scala3doc:
6464
projectLogo: Option[String] = None,
6565
defaultSyntax: CommentSyntax = CommentSyntax.Markdown,
6666
sourceLinks: List[String] = Nil,
67-
revision: Option[String] = None
67+
revision: Option[String] = None,
68+
externalMappings: List[List[String]]
6869
)
6970

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

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

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,10 @@ class Scala3docArgs extends SettingGroup with CommonScalaSettings:
3434
val revision: Setting[String] =
3535
StringSetting("-revision", "revision", "Revision (branch or ref) used to build project project", "")
3636

37-
def scala3docSpecificSettings: Set[Setting[_]] = Set(sourceLinks, syntax, revision)
37+
val externalDocumentationMappings: Setting[String] =
38+
StringSetting("-external-mappings", "external-mappings", "Mapping between regex matching class file and external documentation", "")
39+
40+
def scala3docSpecificSettings: Set[Setting[_]] = Set(sourceLinks, syntax, revision, externalDocumentationMappings)
3841

3942
object Scala3docArgs:
4043
def extract(args: List[String], rootCtx: CompilerContext):(Scala3doc.Args, CompilerContext) =
@@ -95,6 +98,7 @@ object Scala3docArgs:
9598
CommentSyntax.default
9699
}
97100
}
101+
val externalMappings = externalDocumentationMappings.get.split(":::").map(_.split("::").toList).toList
98102

99103
unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
100104
report.warning(s"Setting ${s.name} is currently not supported.")
@@ -115,6 +119,7 @@ object Scala3docArgs:
115119
projectLogo.nonDefault,
116120
parseSyntax,
117121
sourceLinks.nonDefault.fold(Nil)(_.split(",").toList),
118-
revision.nonDefault
122+
revision.nonDefault,
123+
externalMappings
119124
)
120125
(docArgs, newContext)

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ class SymOps[Q <: Quotes](val q: Q):
111111
val originPath = {
112112
import q.reflect._
113113
import dotty.tools.dotc
114-
given ctx as dotc.core.Contexts.Context = q.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
114+
given ctx: dotc.core.Contexts.Context = q.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
115115
val csym = sym.asInstanceOf[dotc.core.Symbols.Symbol]
116116
Option(csym.associatedFile).map(_.path).fold("")(p => s"[origin:$p]")
117117
}

0 commit comments

Comments
 (0)