Merge pull request #58 from 2m/wip-scaladoc-for-java-class-2m

Link to scaladocs when javadoc link is not found

Author: 2m

src/main/scala/com/lightbend/paradox/apidoc/ApidocDirective.scala

@@ -20,7 +20,13 @@ import com.lightbend.paradox.markdown.InlineDirective
 import org.pegdown.Printer
 import org.pegdown.ast.{DirectiveNode, TextNode, Visitor}
 
-class ApidocDirective(allClassesAndObjects: IndexedSeq[String]) extends InlineDirective("apidoc") {
+class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[String, String])
+    extends InlineDirective("apidoc") {
+  final val JavadocProperty = raw"""javadoc\.(.*)\.base_url""".r
+  final val JavadocBaseUrls = properties.collect {
+    case (JavadocProperty(pkg), url) => pkg -> url
+  }
+
   val allClasses = allClassesAndObjects.filterNot(_.endsWith("$"))
 
   private case class Query(pattern: String, generics: String, linkToObject: Boolean) {
@@ -74,7 +80,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String]) extends InlineDi
     }
   }
 
-  def syntheticNode(group: String, label: String, fqcn: String, node: DirectiveNode): DirectiveNode = {
+  def syntheticNode(group: String, doctype: String, label: String, fqcn: String, node: DirectiveNode): DirectiveNode = {
     val syntheticSource = new DirectiveNode.Source.Direct(fqcn)
     val attributes      = new org.pegdown.ast.DirectiveAttributes.AttributeMap()
     new DirectiveNode(
@@ -86,7 +92,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String]) extends InlineDi
       null,
       new DirectiveNode(
         DirectiveNode.Format.Inline,
-        group + "doc",
+        doctype + "doc",
         label,
         syntheticSource,
         node.attributes,
@@ -111,14 +117,22 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String]) extends InlineDi
       case 1 if matches(0).contains("adsl") =>
         throw new java.lang.IllegalStateException(s"Match for $query only found in one language: ${matches(0)}")
       case 1 =>
-        syntheticNode("scala", query.scalaLabel(matches(0)), matches(0) + scalaClassSuffix, node).accept(visitor)
-        syntheticNode("java", query.javaLabel(matches(0)), matches(0), node).accept(visitor)
+        val pkg = matches(0)
+        syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
+        if (hasJavadocUrl(pkg))
+          syntheticNode("java", "java", query.javaLabel(pkg), pkg, node).accept(visitor)
+        else
+          syntheticNode("java", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
       case 2 if matches.forall(_.contains("adsl")) =>
-        matches.foreach(m => {
-          if (!m.contains("javadsl"))
-            syntheticNode("scala", query.scalaLabel(m), m + scalaClassSuffix, node).accept(visitor)
-          if (!m.contains("scaladsl"))
-            syntheticNode("java", query.javaLabel(m), m, node).accept(visitor)
+        matches.foreach(pkg => {
+          if (!pkg.contains("javadsl"))
+            syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
+          if (!pkg.contains("scaladsl")) {
+            if (hasJavadocUrl(pkg))
+              syntheticNode("java", "java", query.javaLabel(pkg), pkg, node).accept(visitor)
+            else
+              syntheticNode("java", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
+          }
         })
       case n =>
         throw new java.lang.IllegalStateException(
@@ -128,4 +142,15 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String]) extends InlineDi
     }
   }
 
+  /**
+   * Logic borrowed from Paradox project:
+   * https://github.com/lightbend/paradox/blob/b271a6bbd249515405a06df58f298a57c34afeb5/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala#L276
+   */
+  private def hasJavadocUrl(pkg: String) = {
+    val levels     = pkg.split("[.]")
+    val packages   = (1 until levels.size).map(levels.take(_).mkString("."))
+    val javadocUrl = packages.reverse.collectFirst(JavadocBaseUrls)
+    javadocUrl.exists(!_.isEmpty)
+  }
+
 }

src/main/scala/com/lightbend/paradox/apidoc/ApidocPlugin.scala

@@ -54,8 +54,8 @@ object ApidocPlugin extends AutoPlugin {
           val allClasses = scanner.getAllClasses.getNames.asScala.toVector
           Def.task {
             Seq(
-              { _: Writer.Context ⇒
-                new ApidocDirective(allClasses)
+              { ctx: Writer.Context =>
+                new ApidocDirective(allClasses, ctx.properties)
               }
             )
           }

src/sbt-test/apidoc/scaladoc-for-java-class/build.sbt

@@ -0,0 +1,13 @@
+libraryDependencies += "com.typesafe.akka" %% "akka-stream-typed" % "2.5.25"
+
+enablePlugins(ParadoxPlugin)
+paradoxTheme := None
+paradoxGroups := Map("Language" -> Seq("Java", "Scala"))
+paradoxProperties ++= Map(
+  "scaladoc.akka.base_url" -> "akka-scaladoc",
+  "scaladoc.akka.stream.base_url" -> "akka-stream-scaladoc",
+  "javadoc.akka.base_url" -> "akka-javadoc",
+  "javadoc.akka.stream.base_url" -> ""
+)
+
+apidocRootPackage := "akka"

src/sbt-test/apidoc/scaladoc-for-java-class/expected/index.html

@@ -0,0 +1,3 @@
+<p>Api link to a class that is both in scaladsl and javadsl packages, but has no javadoc configured: <span class="group-java"><a href="akka-stream-scaladoc/akka/stream/javadsl/Flow.html">Flow</a></span><span class="group-scala"><a href="akka-stream-scaladoc/akka/stream/scaladsl/Flow.html">Flow</a></span></p>
+<p>Api link to a class that is in common package, but has no javadoc configured <span class="group-scala"><a href="akka-stream-scaladoc/akka/stream/stage/GraphStage.html">GraphStage</a></span><span class="group-java"><a href="akka-stream-scaladoc/akka/stream/stage/GraphStage.html">GraphStage</a></span></p>
+<p>Api link to a class that is both in scaladsl and javadsl packages, and has javadoc configured: <span class="group-java"><a href="akka-javadoc/?akka/actor/typed/javadsl/Behaviors.html">Behaviors</a></span><span class="group-scala"><a href="akka-scaladoc/akka/actor/typed/scaladsl/Behaviors.html">Behaviors</a></span></p>

src/sbt-test/apidoc/scaladoc-for-java-class/project/plugins.sbt

@@ -0,0 +1 @@
+addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-apidoc" % sys.props("project.version"))

src/sbt-test/apidoc/scaladoc-for-java-class/src/main/paradox/_template/page.st

@@ -0,0 +1 @@
+$page.content$

src/sbt-test/apidoc/scaladoc-for-java-class/src/main/paradox/index.md

@@ -0,0 +1,5 @@
+Api link to a class that is both in scaladsl and javadsl packages, but has no javadoc configured: @apidoc[Flow]
+
+Api link to a class that is in common package, but has no javadoc configured @apidoc[GraphStage]
+
+Api link to a class that is both in scaladsl and javadsl packages, and has javadoc configured: @apidoc[Behaviors]

src/sbt-test/apidoc/scaladoc-for-java-class/test

@@ -0,0 +1,3 @@
+> paradox
+
+$ must-mirror target/paradox/site/main/index.html expected/index.html

src/test/scala/com/lightbend/paradox/apidoc/ApidocDirectiveSpec.scala

@@ -53,7 +53,7 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
     verbatimSerializers = Writer.defaultVerbatims,
     serializerPlugins = Writer.defaultPlugins(
       Writer.defaultDirectives ++ Seq(
-            (_: Writer.Context) => new ApidocDirective(allClasses)
+            (ctx: Writer.Context) => new ApidocDirective(allClasses, ctx.properties)
           )
     )
   )