Support linking to method anchors (#81)

* Support linking to method anchors
* Document the variations in the readme
* Scala 2.12.10
* cache coursier dir

Author: ennru

.travis.yml

@@ -1,6 +1,6 @@
 language: scala
 jdk: openjdk8
-scala: 2.12.8
+scala: 2.12.10
 
 jobs:
   include:
@@ -28,6 +28,7 @@ stages:
 
 cache:
   directories:
+    - $HOME/.cache/coursier
     - $HOME/.ivy2/cache
     - $HOME/.sbt
 

README.md

@@ -19,10 +19,60 @@ You can now create 'grouped' javadoc/scaladoc references in paradox like:
 Look into the documentation for @apidoc[MyClass].
 ```
 
-This will automatically find the FQDN of the class when it is unique. When the
+This will automatically find the FQCN of the class when it is unique. When the
 name does not uniquely identify the class, the plugin will check for the
 `scaladsl`/`javadsl` package convention found in Akka projects. If that doesn't
-produce an unambigious result, you will have to use the FQDN.
+produce an unambigious result, you will have to use the FQCN.
+
+## Examples
+
+[See details in the tests](/src/test/scala/com/lightbend/paradox/apidoc/ApidocDirectiveSpec.scala)
+
+* `@apidoc[Actor]` (Just one class exists.)
+    * classes: `akka.actor.Actor`
+    * Scala:  `Actor` - `akka/actor/Actor.html`
+    * Java:  `Actor` - `akka/actor/Actor.html`
+
+* `@apidoc[Flow]` (Both scaladoc and javadoc exist.)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: Flow - `akka/stream/scaladsl/Flow.html`
+    * Java: Flow -  `akka/stream/javadsl/Flow.html`
+
+* `@apidoc[Marshaller]` (The scaladoc/javadoc split can be on different package depth.)
+    * classes: `akka.http.scaladsl.marshalling.Marshaller`, `akka.http.javadsl.marshalling.Marshaller`
+    * Scala: Marshaller - `akka/http/scaladsl/marshalling/Marshaller.html`
+    * Java: Marshaller - `akka/http/javadsl/marshalling/Marshaller.html`
+
+* `@apidoc[typed.*.Replicator$]` (The classes exist in multiple places.)
+    * classes: `akka.cluster.ddata.Replicator$`, `akka.cluster.ddata.typed.scaladsl.Replicator$`, `akka.cluster.ddata.typed.javadsl.Replicator$`
+`   * Scala: Replicator - `akka/cluster/ddata/typed/scaladsl/Replicator$.html`
+    * Java: Replicator - `akka/cluster/ddata/typed/javadsl/Replicator.html`
+
+* `@apidoc[akka.stream.(javadsl|scaladsl).Concat]` (The classes exist in even more places.)
+    * classes: `akka.stream.impl.Concat`, `akka.stream.scaladsl.Concat$`, `akka.stream.scaladsl.Concat`, `akka.stream.javadsl.Concat$`
+    * Scala: Concat - `akka/stream/scaladsl/Concat.html`
+    * Java: Concat - `akka/stream/javadsl/Concat.html`
+
+* `@apidoc[ClusterClient$]` (Link to scala object.)
+    * classes: `akka.cluster.client.ClusterClient`
+    * Scala: ClusterClient - `akka/cluster/client/ClusterClient$.html`
+    * Java: ClusterClient - `akka/cluster/client/ClusterClient.html`
+
+* `@apidoc[Source[ServerSentEvent, \_]]` (Show type paramters.)
+    * classes: `akka.stream.scaladsl.Source` - `akka.stream.javadsl.Source`
+    * Scala: Source\[ServerSentEvent, _\] - `akka/stream/scaladsl/Source.html`
+    * Java: Source\<ServerSentEvent, ?\> - `akka/stream/javadsl/Source.html`
+
+* `@apidoc[TheClass.method](Flow)` (Different link text than the class name.)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: TheClass.method<br>`akka/stream/scaladsl/Flow.html`
+    * Java: TheClass.method<br>`akka/stream/javadsl/Flow.html`
+
+* `@apidoc[method](Flow) { scala="#method():Unit" java="#method()" }` (Link to method anchors.)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: method - `akka/stream/scaladsl/Flow.html#method():Unit`
+    * Java: method - `akka/stream/javadsl/Flow.html#method()`
+
 
 To limit the packages that are searched for classes, configure the
 `apidocRootPackage` setting:

build.sbt

@@ -1,6 +1,6 @@
 import scala.collection.JavaConverters._
 
-scalaVersion := "2.12.9"
+scalaVersion := "2.12.10"
 
 sbtPlugin        := true
 crossSbtVersions := List("1.0.0")

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

@@ -18,6 +18,7 @@ package com.lightbend.paradox.apidoc
 
 import com.lightbend.paradox.markdown.InlineDirective
 import org.pegdown.Printer
+import org.pegdown.ast.DirectiveNode.Source
 import org.pegdown.ast.{DirectiveNode, Visitor}
 
 class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[String, String])
@@ -29,9 +30,13 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
 
   val allClasses = allClassesAndObjects.filterNot(_.endsWith("$"))
 
-  private case class Query(pattern: String, generics: String, linkToObject: Boolean) {
+  private case class Query(label: Option[String], pattern: String, generics: String, linkToObject: Boolean) {
     def scalaLabel(matched: String): String =
-      matched.split('.').last + generics
+      label match {
+        case None => matched.split('.').last + generics
+        case Some(la) => la + generics
+      }
+
     def javaLabel(matched: String): String =
       scalaLabel(matched)
         .replaceAll("\\[", "<")
@@ -44,19 +49,33 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
   }
   private object Query {
     def apply(label: String): Query = {
-      val (pattern, generics) = label.indexOf('[') match {
-        case -1 => (label, "")
-        case n => label.replaceAll("\\\\_", "_").splitAt(n)
-      }
+      val (pattern, generics) = splitGenerics(label)
+      if (pattern.endsWith("$"))
+        Query(None, pattern.init, generics, linkToObject = true)
+      else
+        Query(None, pattern, generics, linkToObject = false)
+    }
+
+    def apply(label: String, pattern: String): Query = {
+      val (labelPattern, generics) = splitGenerics(label)
       if (pattern.endsWith("$"))
-        Query(pattern.init, generics, linkToObject = true)
+        Query(Some(labelPattern), pattern.init, generics, linkToObject = true)
       else
-        Query(pattern, generics, linkToObject = false)
+        Query(Some(labelPattern), pattern, generics, linkToObject = false)
     }
+
+    private def splitGenerics(label: String): (String, String) =
+      label.indexOf('[') match {
+        case -1 => (label, "")
+        case n => label.replaceAll("\\\\_", "_").splitAt(n)
+      }
   }
 
   def render(node: DirectiveNode, visitor: Visitor, printer: Printer): Unit = {
-    val query = Query(node.label)
+    val query = node.source match {
+      case Source.Empty | _: Source.Ref => Query(node.label)
+      case s: Source.Direct => Query(node.label, s.value)
+    }
     if (query.pattern.contains('.')) {
       if (allClasses.contains(query.pattern)) {
         renderMatches(query, Seq(query.pattern), node, visitor, printer)
@@ -84,6 +103,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
       doctype: String,
       label: String,
       fqcn: String,
+      anchor: String,
       node: DirectiveNode
   ): DirectiveNode = {
     val attributes = new org.pegdown.ast.DirectiveAttributes.AttributeMap()
@@ -98,7 +118,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
         DirectiveNode.Format.Inline,
         doctype + "doc",
         label,
-        new DirectiveNode.Source.Direct(fqcn),
+        new DirectiveNode.Source.Direct(fqcn + anchor),
         node.attributes,
         label, // contents
         null
@@ -114,6 +134,8 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
       printer: Printer
   ): Unit = {
     val scalaClassSuffix = if (query.linkToObject) "$" else ""
+    val sAnchor          = node.attributes.value("scala", "")
+    val jAnchor          = node.attributes.value("java", "")
 
     matches.size match {
       case 0 =>
@@ -122,20 +144,22 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
         throw new java.lang.IllegalStateException(s"Match for $query only found in one language: ${matches(0)}")
       case 1 =>
         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)
+        syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, sAnchor, node).accept(visitor)
+        if (hasJavadocUrl(pkg)) {
+          syntheticNode("java", "java", query.javaLabel(pkg), pkg, jAnchor, node).accept(visitor)
+        } else
+          syntheticNode("java", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, jAnchor, node).accept(visitor)
       case 2 if matches.forall(_.contains("adsl")) =>
         matches.foreach(pkg => {
           if (!pkg.contains("javadsl"))
-            syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
+            syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, sAnchor, node)
+              .accept(visitor)
           if (!pkg.contains("scaladsl")) {
             if (hasJavadocUrl(pkg))
-              syntheticNode("java", "java", query.javaLabel(pkg), pkg, node).accept(visitor)
+              syntheticNode("java", "java", query.javaLabel(pkg), pkg, jAnchor, node).accept(visitor)
             else
-              syntheticNode("java", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, node).accept(visitor)
+              syntheticNode("java", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, jAnchor, node)
+                .accept(visitor)
           }
         })
       case n =>

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

@@ -59,6 +59,7 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
   )
 
   implicit val context = writerContextWithProperties(
+    "javadoc.link_style" -> "frames",
     "scaladoc.akka.base_url" -> "https://doc.akka.io/api/akka/2.5",
     "scaladoc.akka.http.base_url" -> "https://doc.akka.io/api/akka-http/current",
     "javadoc.akka.base_url" -> "https://doc.akka.io/japi/akka/2.5",
@@ -127,7 +128,7 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
       )
   }
 
-  it should "find a class by partiql fqdn" in {
+  it should "find a class by partial fqcn" in {
     markdown("@apidoc[actor.typed.ActorRef]") shouldEqual
       html(
         """<p><span class="group-scala">
@@ -176,4 +177,44 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
           |</p>""".stripMargin
       )
   }
+
+  "Anchor attributes" should "be used" in {
+    markdown("""The @apidoc[Flow] { scala="#method():Unit" java="#method()" } thingie""") shouldEqual
+      html(
+        """<p>The <span class="group-java">
+          |<a href="https://doc.akka.io/japi/akka/2.5/?akka/stream/javadsl/Flow.html#method()" title="akka.stream.javadsl.Flow"><code>Flow</code></a></span><span class="group-scala">
+          |<a href="https://doc.akka.io/api/akka/2.5/akka/stream/scaladsl/Flow.html#method():Unit" title="akka.stream.scaladsl.Flow"><code>Flow</code></a></span>
+          |thingie</p>""".stripMargin
+      )
+  }
+
+  "Directive with label and source" should "use the source as class pattern" in {
+    markdown("The @apidoc[TheClass.method](Flow) { .scaladoc a=1 } thingie") shouldEqual
+      html(
+        """<p>The <span class="group-java">
+          |<a href="https://doc.akka.io/japi/akka/2.5/?akka/stream/javadsl/Flow.html" title="akka.stream.javadsl.Flow"><code>TheClass.method</code></a></span><span class="group-scala">
+          |<a href="https://doc.akka.io/api/akka/2.5/akka/stream/scaladsl/Flow.html" title="akka.stream.scaladsl.Flow"><code>TheClass.method</code></a></span>
+          |thingie</p>""".stripMargin
+      )
+  }
+
+  it should "adapt generics notation from the label" in {
+    markdown("The @apidoc[TheClass[File].method[String]](Flow) { .scaladoc a=1 } thingie") shouldEqual
+      html(
+        """<p>The <span class="group-java">
+          |<a href="https://doc.akka.io/japi/akka/2.5/?akka/stream/javadsl/Flow.html" title="akka.stream.javadsl.Flow"><code>TheClass&lt;File&gt;.method&lt;String&gt;</code></a></span><span class="group-scala">
+          |<a href="https://doc.akka.io/api/akka/2.5/akka/stream/scaladsl/Flow.html" title="akka.stream.scaladsl.Flow"><code>TheClass[File].method[String]</code></a></span>
+          |thingie</p>""".stripMargin
+      )
+  }
+
+  it should "use anchors" in {
+    markdown("""The @apidoc[TheClass[File].method[String]](Flow) { scala="#method():Unit" java="#method()" } thingie""") shouldEqual
+      html(
+        """<p>The <span class="group-java">
+          |<a href="https://doc.akka.io/japi/akka/2.5/?akka/stream/javadsl/Flow.html#method()" title="akka.stream.javadsl.Flow"><code>TheClass&lt;File&gt;.method&lt;String&gt;</code></a></span><span class="group-scala">
+          |<a href="https://doc.akka.io/api/akka/2.5/akka/stream/scaladsl/Flow.html#method():Unit" title="akka.stream.scaladsl.Flow"><code>TheClass[File].method[String]</code></a></span>
+          |thingie</p>""".stripMargin
+      )
+  }
 }