Add support for legacy external mappings -doc-external-doc

Author: pikinier20

scaladoc/src/dotty/tools/scaladoc/ExternalDocLink.scala

@@ -18,31 +18,44 @@ enum DocumentationKind:
   case Scaladoc3 extends DocumentationKind
 
 object ExternalDocLink:
-  def parse(mapping: String): Either[String, ExternalDocLink] =
-    def fail(msg: String) = Left(s"Unable to process external mapping $mapping. $msg")
+  private def fail(mapping: String, msg: String) = Left(s"Unable to process external mapping $mapping. $msg")
+
+  private def tryParse[T](mapping: String, descr: String)(op: => T): Either[String, T] = Try(op) match {
+    case Success(v) => Right(v)
+    case Failure(e) => fail(mapping, s"Unable to parse $descr. Exception $e occured")
+  }
 
-    def tryParse[T](descr: String)(op: => T): Either[String, T] = Try(op) match {
-      case Success(v) => Right(v)
-      case Failure(e) => fail(s"Unable to parse $descr. Exception $e occured")
-    }
+  def parseLegacy(mapping: String): Either[String, ExternalDocLink] =
+    mapping.split("#").toList match
+      case path :: apiUrl :: Nil => for {
+        url <- tryParse(mapping, "url")(URL(apiUrl))
+      } yield ExternalDocLink(
+        List(s"$path.*".r),
+        url,
+        DocumentationKind.Scaladoc2,
+        None
+      )
+      case _ => fail(mapping, "Wrong format of legacy external mapping. path#apiUrl format is accepted.")
+
+  def parse(mapping: String): Either[String, ExternalDocLink] =
 
     def parsePackageList(elements: List[String]) = elements match
-     case List(urlStr) => tryParse("packageList")(Some(URL(urlStr)))
+     case List(urlStr) => tryParse(mapping, "packageList")(Some(URL(urlStr)))
      case Nil => Right(None)
-     case other => fail(s"Provided multiple package lists: $other")
+     case other => fail(mapping, s"Provided multiple package lists: $other")
 
     def doctoolByName(name: String) = name match
       case "javadoc" => Right(DocumentationKind.Javadoc)
       case "scaladoc2" => Right(DocumentationKind.Scaladoc2)
       case "scaladoc3" => Right(DocumentationKind.Scaladoc3)
-      case other => fail(s"Unknown doctool: $other")
+      case other => fail(mapping, s"Unknown doctool: $other")
 
 
     mapping.split("::").toList match
       case regexStr :: docToolStr :: urlStr :: rest =>
         for {
-          regex <- tryParse("regex")(regexStr.r)
-          url <- tryParse("url")(URL(urlStr))
+          regex <- tryParse(mapping, "regex")(regexStr.r)
+          url <- tryParse(mapping, "url")(URL(urlStr))
           doctool <- doctoolByName(docToolStr)
           packageList <- parsePackageList(rest)
         } yield ExternalDocLink(
@@ -52,4 +65,4 @@ object ExternalDocLink:
             packageList
           )
       case _ =>
-        fail("Accepted format: `regexStr::docToolStr::urlStr[::rest]`")
+        fail(mapping, "Accepted format: `regexStr::docToolStr::urlStr[::rest]`")

scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala

@@ -170,6 +170,7 @@ object Scaladoc:
         }
       }
       val legacySourceLinkList = if legacySourceLink.get.nonEmpty then List(legacySourceLink.get) else Nil
+
       val externalMappings =
         externalDocumentationMappings.get.flatMap( s =>
             ExternalDocLink.parse(s).fold(left => {
@@ -179,6 +180,15 @@ object Scaladoc:
           )
         )
 
+      val legacyExternalMappings =
+        legacyExternalDocumentationMappings.get.flatMap { s =>
+          ExternalDocLink.parseLegacy(s).fold(left => {
+              report.warning(left)
+              None
+            }, right => Some(right)
+          )
+        }
+
       val socialLinksParsed =
         socialLinks.get.flatMap { s =>
           SocialLinks.parse(s).fold(left => {
@@ -211,7 +221,7 @@ object Scaladoc:
         parseSyntax,
         sourceLinks.get ++ legacySourceLinkList,
         revision.nonDefault,
-        externalMappings,
+        externalMappings ++ legacyExternalMappings,
         socialLinksParsed,
         skipById.get ++ deprecatedSkipPackages.get,
         skipByRegex.get,

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

@@ -55,6 +55,9 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
       "Mapping between regexes matching classpath entries and external documentation. " +
         "'regex::[scaladoc|scaladoc|javadoc]::path' syntax is used")
 
+  val legacyExternalDocumentationMappings: Setting[List[String]] =
+    MultiStringSetting("-doc-external-doc", "legacy-external-mappings", "Legacy option from Scala 2. Mapping betweeen path and external documentation. Use -external-mappings instead.")
+
   val socialLinks: Setting[List[String]] =
     MultiStringSetting("-social-links", "social-links",
       "Links to social sites. '[github|twitter|gitter|discord]::link' syntax is used. " +

scaladoc/src/dotty/tools/scaladoc/tasty/SymOps.scala

@@ -271,7 +271,8 @@ class SymOpsWithLinkCache:
             val extLink = if externalLinkCache.contains(csym.associatedFile)
               then externalLinkCache(csym.associatedFile)
               else {
-                val calculatedLink = Option(csym.associatedFile).map(_.path).flatMap { path =>
+                def calculatePath(file: AbstractFile): String = file.underlyingSource.filter(_ != file).fold("")(f => calculatePath(f) + "/") + file.path
+                val calculatedLink = Option(csym.associatedFile).map(f => calculatePath(f)).flatMap { path =>
                   dctx.externalDocumentationLinks.find(_.originRegexes.exists(r => r.matches(path)))
                 }
                 externalLinkCache += (csym.associatedFile -> calculatedLink)

scaladoc/test/dotty/tools/scaladoc/ExternalLocationProviderIntegrationTest.scala

@@ -45,6 +45,18 @@ class Scaladoc3ExternalLocationProviderIntegrationTest extends ExternalLocationP
   )
 )
 
+class Scaladoc2LegacyExternalLocationProviderIntegrationTest extends LegacyExternalLocationProviderIntegrationTest(
+  "externalScaladoc2",
+  List(".*scala.*#https://www.scala-lang.org/api/current/"),
+  List(
+    "https://www.scala-lang.org/api/current/scala/util/matching/Regex$$Match.html",
+    "https://www.scala-lang.org/api/current/scala/Predef$.html#String",
+    "https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html",
+    "https://www.scala-lang.org/api/current/scala/collection/IterableOnceOps.html#addString(b:StringBuilder,start:String,sep:String,end:String):StringBuilder",
+    "https://www.scala-lang.org/api/current/scala/collection/IterableOnceOps.html#mkString(start:String,sep:String,end:String):String"
+  )
+)
+
 
 abstract class ExternalLocationProviderIntegrationTest(
   name: String,
@@ -85,3 +97,16 @@ abstract class ExternalLocationProviderIntegrationTest(
     }
   } :: Nil
 
+abstract class LegacyExternalLocationProviderIntegrationTest(
+  name: String,
+  mappings: Seq[String],
+  expectedLinks: Seq[String]
+) extends ExternalLocationProviderIntegrationTest(name, mappings, expectedLinks):
+
+  override def args = super.args.copy(
+      externalMappings = mappings.flatMap( s =>
+        ExternalDocLink.parseLegacy(s).fold(left => None, right => Some(right)
+      )
+    ).toList
+  )
+