Add cli parameter to handle external documentation mappings

Author: pikinier20

scala3doc/src/dotty/dokka/DocContext.scala

@@ -19,6 +19,7 @@ import java.io.ByteArrayOutputStream
 import java.io.PrintStream
 import scala.io.Codec
 import java.net.URL
+import scala.util.Try
 
 type CompilerContext = dotty.tools.dotc.core.Contexts.Context
 
@@ -94,23 +95,69 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
         sourceLinks
       )(using compilerContext))
 
-    val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = List(
-      Scala3docExternalDocumentationLink(
-        List(raw".*scala\/quoted.*".r),
-        new URL("http://127.0.0.1:5500/scala3doc/output/scala3/"),
-        DocumentationKind.Scala3doc
-      ).withPackageList(new URL("http://127.0.0.1:5500/scala3doc/output/scala3/-scala%203/package-list")),
-      Scala3docExternalDocumentationLink(
-        List(raw".*java.*".r),
-        new URL("https://docs.oracle.com/javase/8/docs/api/"),
-        DocumentationKind.Javadoc
-      ).withPackageList(new URL("https://docs.oracle.com/javase/8/docs/api/package-list")),
-      Scala3docExternalDocumentationLink(
-        List(raw".*scala.*".r),
-        new URL("https://www.scala-lang.org/api/current/"),
-        DocumentationKind.Scaladoc
-      )
-    )
+    def parseDocTool(docTool: String) = docTool match {
+      case "scaladoc" => Some(DocumentationKind.Scaladoc)
+      case "scala3doc" => Some(DocumentationKind.Scala3doc)
+      case "javadoc" => Some(DocumentationKind.Javadoc)
+      case other => None
+    }
+    val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = args.externalMappings.filter(_.size >= 3).flatMap { mapping =>
+      val regexStr = mapping(0)
+      val docTool = mapping(1)
+      val urlStr = mapping(2)
+      val packageListUrlStr = if mapping.size > 3 then Some(mapping(3)) else None
+      val regex = Try(regexStr.r).toOption
+      val url = Try(URL(urlStr)).toOption
+      val packageListUrl = Try(packageListUrlStr.map(URL(_)))
+        .fold(
+          e => {
+          logger.warn(s"Wrong packageListUrl parameter in external mapping. Found '$packageListUrlStr'. " +
+            s"Package list url will be omitted")
+          None},
+          res => res
+        )
+
+      val parsedDocTool = parseDocTool(docTool)
+      val res = if regexStr.isEmpty then
+        logger.warn(s"Wrong regex parameter in external mapping. Found '$regexStr'. Mapping will be omitted")
+        None
+      else if url.isEmpty then
+        logger.warn(s"Wrong url parameter in external mapping. Found '$urlStr'. Mapping will be omitted")
+        None
+      else if parsedDocTool.isEmpty then
+        logger.warn(s"Wrong doc-tool parameter in external mapping. " +
+          s"Expected one of: 'scaladoc', 'scala3doc', 'javadoc'. Found:'$docTool'.  Mapping will be omitted "
+        )
+        None
+      else
+        Some(
+          Scala3docExternalDocumentationLink(
+            List(regexStr.r),
+            URL(urlStr),
+            parsedDocTool.get,
+            packageListUrlStr.map(URL(_))
+          )
+        )
+      res
+    }
+
+    //val externalDocumentationLinks: List[Scala3docExternalDocumentationLink] = List(
+      // Scala3docExternalDocumentationLink(
+      //   List(raw".*scala\/quoted.*".r),
+      //   new URL("http://127.0.0.1:5500/scala3doc/output/scala3/"),
+      //   DocumentationKind.Scala3doc
+      // ).withPackageList(new URL("http://127.0.0.1:5500/scala3doc/output/scala3/-scala%203/package-list")),
+      // Scala3docExternalDocumentationLink(
+      //   List(raw".*java.*".r),
+      //   new URL("https://docs.oracle.com/javase/8/docs/api/"),
+      //   DocumentationKind.Javadoc
+      // ).withPackageList(new URL("https://docs.oracle.com/javase/8/docs/api/package-list")),
+      // Scala3docExternalDocumentationLink(
+      //   List(raw".*scala.*".r),
+      //   new URL("https://www.scala-lang.org/api/current/"),
+      //   DocumentationKind.Scaladoc
+      // )
+    //)
 
     override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] =
       JNil

scala3doc/src/dotty/dokka/DottyDokkaPlugin.scala

@@ -183,7 +183,7 @@ class DottyDokkaPlugin extends DokkaJavaPlugin:
 
   val scalaExternalLocationProviderFactory = extend(
     _.extensionPoint(dokkaBase.getExternalLocationProviderFactory)
-      .fromRecipe{ case c as given DokkaContext => new ScalaExternalLocationProviderFactory }
+      .fromRecipe{ case c @ given DokkaContext => new ScalaExternalLocationProviderFactory }
       .overrideExtension(dokkaBase.getDokkaLocationProvider)
   )
 

scala3doc/src/dotty/dokka/Scala3doc.scala

@@ -64,7 +64,8 @@ object Scala3doc:
     projectLogo: Option[String] = None,
     defaultSyntax: CommentSyntax = CommentSyntax.Markdown,
     sourceLinks: List[String] = Nil,
-    revision: Option[String] = None
+    revision: Option[String] = None,
+    externalMappings: List[List[String]]
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =

scala3doc/src/dotty/dokka/Scala3docArgs.scala

@@ -34,7 +34,10 @@ class Scala3docArgs extends SettingGroup with CommonScalaSettings:
   val revision: Setting[String] =
     StringSetting("-revision", "revision", "Revision (branch or ref) used to build project project", "")
 
-  def scala3docSpecificSettings: Set[Setting[_]] = Set(sourceLinks, syntax, revision)
+  val externalDocumentationMappings: Setting[String] =
+    StringSetting("-external-mappings", "external-mappings", "Mapping between regex matching class file and external documentation", "")
+
+  def scala3docSpecificSettings: Set[Setting[_]] = Set(sourceLinks, syntax, revision, externalDocumentationMappings)
 
 object Scala3docArgs:
   def extract(args: List[String], rootCtx: CompilerContext):(Scala3doc.Args, CompilerContext) =
@@ -95,6 +98,7 @@ object Scala3docArgs:
         CommentSyntax.default
       }
     }
+    val externalMappings = externalDocumentationMappings.get.split(":::").map(_.split("::").toList).toList
 
     unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
       report.warning(s"Setting ${s.name} is currently not supported.")
@@ -115,6 +119,7 @@ object Scala3docArgs:
       projectLogo.nonDefault,
       parseSyntax,
       sourceLinks.nonDefault.fold(Nil)(_.split(",").toList),
-      revision.nonDefault
+      revision.nonDefault,
+      externalMappings
     )
     (docArgs, newContext)

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

@@ -114,7 +114,7 @@ class SymOps[Q <: Quotes](val q: Q):
         val originPath = {
             import q.reflect._
             import dotty.tools.dotc
-            given ctx as dotc.core.Contexts.Context = q.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
+            given ctx: dotc.core.Contexts.Context = q.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
             val csym = sym.asInstanceOf[dotc.core.Symbols.Symbol]
             Option(csym.associatedFile).map(_.path).fold("")(p => s"[origin:$p]")
         }