Scaladoc/Javadoc: wrap link text in '<code>' (#378)

* Scaladoc/Javadoc: wrap link text in '<code>' * Adapt unit tests
lightbend · Oct 7, 2019 · 990ac43 · 990ac43
1 parent 57ce487
commit 990ac43
Show file tree

Hide file tree

Showing 7 changed files with 42 additions and 38 deletions.
diff --git a/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala b/core/src/main/scala/com/lightbend/paradox/markdown/Directive.scala
@@ -212,10 +212,12 @@ object LinkDirective {
 abstract class ExternalLinkDirective(names: String*)
   extends InlineDirective(names: _*) with SourceDirective {
 
-  def resolveLink(node: DirectiveNode, location: String): Url
+  protected def resolveLink(node: DirectiveNode, location: String): Url
 
   def render(node: DirectiveNode, visitor: Visitor, printer: Printer): Unit =
-    new ExpLinkNode(title(node, page), resolvedSource(node, page), node.contentsNode).accept(visitor)
+    new ExpLinkNode(title(node, page), resolvedSource(node, page), linkContents(node)).accept(visitor)
+
+  protected def linkContents(node: DirectiveNode): Node = node.contentsNode
 
   override protected def resolvedSource(node: DirectiveNode, page: Page): String = {
     val link = super.resolvedSource(node, page)
@@ -279,6 +281,8 @@ abstract class ApiDocDirective(name: String)
     case (property @ ApiDocProperty(pkg), url) => (pkg, PropertyUrl(property, variables.get))
   }
 
+  override protected def linkContents(node: DirectiveNode): Node = new CodeNode(node.contents)
+
   override protected def title(node: DirectiveNode, page: Page): String = {
     val link = extractLink(node, page)
     try {
@@ -296,7 +300,7 @@ abstract class ApiDocDirective(name: String)
     }
   }
 
-  def resolveLink(node: DirectiveNode, link: String): Url = {
+  override protected def resolveLink(node: DirectiveNode, link: String): Url = {
     val levels = link.split("[.]")
     val packages = (1 to levels.init.size).map(levels.take(_).mkString("."))
     val baseUrl = packages.reverse.collectFirst(baseUrls).getOrElse(defaultBaseUrl).resolve()

diff --git a/plugin/src/sbt-test/paradox/parameterized-links/build.sbt b/plugin/src/sbt-test/paradox/parameterized-links/build.sbt
@@ -33,5 +33,5 @@ TaskKey[Unit]("checkJavadocJavalibContent") := {
   assert(file.exists, s"${file.getAbsolutePath} did not exist")
   val content = IO.readLines(file).mkString
   assert(content.matches(
-    raw"""<p><a href="https://docs.oracle.com/javase/\d+/docs/api/\?java/io/File\.html#separator" title="java.io.File">File\.separator</a></p>"""))
+    raw"""<p><a href="https://docs.oracle.com/javase/\d+/docs/api/\?java/io/File\.html#separator" title="java.io.File"><code>File\.separator</code></a></p>"""))
 }
diff --git a/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html b/plugin/src/sbt-test/paradox/parameterized-links/expected/javadoc.html
@@ -1,3 +1,3 @@
-<p><a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor">Actor</a></p>
-<p><a href="http://doc.akka.io/japi/akka-http/10.0.0/?akka/http/javadsl/Http.html#shutdownAllConnectionPools--" title="akka.http.javadsl.Http">Http</a></p>
-<p><a href="https://api.example.com/java/?org/example/Server.html" title="org.example.Server">Server</a></p>
+<p><a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a></p>
+<p><a href="http://doc.akka.io/japi/akka-http/10.0.0/?akka/http/javadsl/Http.html#shutdownAllConnectionPools--" title="akka.http.javadsl.Http"><code>Http</code></a></p>
+<p><a href="https://api.example.com/java/?org/example/Server.html" title="org.example.Server"><code>Server</code></a></p>
diff --git a/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html b/plugin/src/sbt-test/paradox/parameterized-links/expected/scaladoc.html
@@ -1,3 +1,3 @@
-<p>Use a <a href="http://www.scala-lang.org/api/2.11.12/scala/concurrent/Future.html" title="scala.concurrent.Future">Future</a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html" title="akka.actor.Actor">Actor</a>.</p>
-<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http">Http</a></p>
-<p><a href="https://example.org/api/0.1.0/org/example/Server.html#start():Unit" title="org.example.Server">Server#start</a></p>
+<p>Use a <a href="http://www.scala-lang.org/api/2.11.12/scala/concurrent/Future.html" title="scala.concurrent.Future"><code>Future</code></a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a>.</p>
+<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http"><code>Http</code></a></p>
+<p><a href="https://example.org/api/0.1.0/org/example/Server.html#start():Unit" title="org.example.Server"><code>Server#start</code></a></p>
diff --git a/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html b/plugin/src/sbt-test/paradox/scaladoc-2.12/expected/scaladoc-2.12.html
@@ -1,2 +1,2 @@
-<p>Use a <a href="http://www.scala-lang.org/api/2.12.1/scala/concurrent/Future.html" title="scala.concurrent.Future">Future</a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.13/akka/actor/Actor.html" title="akka.actor.Actor">Actor</a>.</p>
-<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http">Http</a></p>
+<p>Use a <a href="http://www.scala-lang.org/api/2.12.1/scala/concurrent/Future.html" title="scala.concurrent.Future"><code>Future</code></a> to avoid that long running operations block the <a href="http://doc.akka.io/api/akka/2.4.13/akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a>.</p>
+<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http"><code>Http</code></a></p>
diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/JavadocDirectiveSpec.scala
@@ -32,39 +32,39 @@ class JavadocDirectiveSpec extends MarkdownBaseSpec {
 
   "javadoc directive" should "create links using configured URL templates" in {
     markdown("@javadoc[Publisher](org.reactivestreams.Publisher)") shouldEqual
-      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher">Publisher</a></p>""")
+      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher"><code>Publisher</code></a></p>""")
   }
 
   it should "support 'javadoc:' as an alternative name" in {
     markdown("@javadoc:[Publisher](org.reactivestreams.Publisher)") shouldEqual
-      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher">Publisher</a></p>""")
+      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher"><code>Publisher</code></a></p>""")
   }
 
   it should "support root relative '...' base urls" in {
     markdown("@javadoc[Url](root.relative.Url)") shouldEqual
-      html("""<p><a href="javadoc/api/?root/relative/Url.html" title="root.relative.Url">Url</a></p>""")
+      html("""<p><a href="javadoc/api/?root/relative/Url.html" title="root.relative.Url"><code>Url</code></a></p>""")
   }
 
   it should "handle method links correctly" in {
     markdown("@javadoc[File.pathSeparator](java.io.File#pathSeparator)") shouldEqual
-      html("""<p><a href="https://docs.oracle.com/javase/8/docs/api/?java/io/File.html#pathSeparator" title="java.io.File">File.pathSeparator</a></p>""")
+      html("""<p><a href="https://docs.oracle.com/javase/8/docs/api/?java/io/File.html#pathSeparator" title="java.io.File"><code>File.pathSeparator</code></a></p>""")
   }
 
   it should "handle class links correctly" in {
     markdown("@javadoc[Http](akka.http.javadsl.Http)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/japi/akka-http/10.0.0/index.html?akka/http/javadsl/Http.html" title="akka.http.javadsl.Http">Http</a></p>""")
+      html("""<p><a href="http://doc.akka.io/japi/akka-http/10.0.0/index.html?akka/http/javadsl/Http.html" title="akka.http.javadsl.Http"><code>Http</code></a></p>""")
     markdown("@javadoc[Actor](akka.actor.Actor)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor">Actor</a></p>""")
+      html("""<p><a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a></p>""")
   }
 
   it should "retain whitespace before or after" in {
     markdown("The @javadoc:[Actor](akka.actor.Actor) class") shouldEqual
-      html("""<p>The <a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor">Actor</a> class</p>""")
+      html("""<p>The <a href="http://doc.akka.io/japi/akka/2.4.10/?akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a> class</p>""")
   }
 
   it should "parse but ignore directive attributes" in {
     markdown("The @javadoc:[Publisher](org.reactivestreams.Publisher) { .javadoc a=1 } spec") shouldEqual
-      html("""<p>The <a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher">Publisher</a> spec</p>""")
+      html("""<p>The <a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher"><code>Publisher</code></a> spec</p>""")
   }
 
   it should "throw exceptions for unconfigured default base URL" in {
@@ -91,13 +91,13 @@ class JavadocDirectiveSpec extends MarkdownBaseSpec {
         |
         |  [Publisher]: org.reactivestreams.Publisher
       """.stripMargin) shouldEqual
-      html("""<p>The <a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher">Publisher</a> spec</p>""")
+      html("""<p>The <a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/?org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher"><code>Publisher</code></a> spec</p>""")
   }
 
   it should "support creating non frame style links" in {
     val ctx = context.andThen(c => c.copy(properties = c.properties.updated("javadoc.link_style", "direct")))
     markdown("@javadoc[Publisher](org.reactivestreams.Publisher)")(ctx) shouldEqual
-      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher">Publisher</a></p>""")
+      html("""<p><a href="http://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/org/reactivestreams/Publisher.html" title="org.reactivestreams.Publisher"><code>Publisher</code></a></p>""")
   }
 
 }
diff --git a/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala b/tests/src/test/scala/com/lightbend/paradox/markdown/ScaladocDirectiveSpec.scala
@@ -31,45 +31,45 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
 
   "Scaladoc directive" should "create links using configured URL templates" in {
     markdown("@scaladoc[Model](org.example.Model)") shouldEqual
-      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model">Model</a></p>""")
+      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model"><code>Model</code></a></p>""")
   }
 
   it should "support 'scaladoc:' as an alternative name" in {
     markdown("@scaladoc:[Model](org.example.Model)") shouldEqual
-      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model">Model</a></p>""")
+      html("""<p><a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model"><code>Model</code></a></p>""")
   }
 
   it should "support root relative '...' base urls" in {
     markdown("@scaladoc:[Url](root.relative.Url)") shouldEqual
-      html("""<p><a href="scaladoc/api/root/relative/Url.html" title="root.relative.Url">Url</a></p>""")
+      html("""<p><a href="scaladoc/api/root/relative/Url.html" title="root.relative.Url"><code>Url</code></a></p>""")
   }
 
   it should "handle method links correctly" in {
     markdown("@scaladoc[???](scala.Predef$#???:Nothing)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/Predef$.html#???:Nothing" title="scala.Predef">???</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/Predef$.html#???:Nothing" title="scala.Predef"><code>???</code></a></p>""")
 
     markdown(
       """@scaladoc:[Actor#preStart]
         |
         |  [Actor#preStart]: akka.actor.Actor#preStart():Unit""") shouldEqual
-      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html#preStart():Unit" title="akka.actor.Actor">Actor#preStart</a></p>""")
+      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html#preStart():Unit" title="akka.actor.Actor"><code>Actor#preStart</code></a></p>""")
   }
 
   it should "handle object links correctly" in {
     markdown("@scaladoc[Http](akka.http.scaladsl.Http$)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http">Http</a></p>""")
+      html("""<p><a href="http://doc.akka.io/api/akka-http/10.0.0/akka/http/scaladsl/Http$.html" title="akka.http.scaladsl.Http"><code>Http</code></a></p>""")
     markdown("@scaladoc[Actor](akka.actor.Actor)") shouldEqual
-      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html" title="akka.actor.Actor">Actor</a></p>""")
+      html("""<p><a href="http://doc.akka.io/api/akka/2.4.10/akka/actor/Actor.html" title="akka.actor.Actor"><code>Actor</code></a></p>""")
   }
 
   it should "retain whitespace before or after" in {
     markdown("The @scaladoc:[Model](org.example.Model) class") shouldEqual
-      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model">Model</a> class</p>""")
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model"><code>Model</code></a> class</p>""")
   }
 
   it should "parse but ignore directive attributes" in {
     markdown("The @scaladoc:[Model](org.example.Model) { .scaladoc a=1 } spec") shouldEqual
-      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model">Model</a> spec</p>""")
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model"><code>Model</code></a> spec</p>""")
   }
 
   it should "throw exceptions for unconfigured default base URL" in {
@@ -90,11 +90,11 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
       "scaladoc.version" -> "2.12.0")
 
     markdown("@scaladoc[Int](scala.Int)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/Int.html" title="scala.Int">Int</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/Int.html" title="scala.Int"><code>Int</code></a></p>""")
     markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/Codec$.html" title="scala.io.Codec">Codec$</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/Codec$.html" title="scala.io.Codec"><code>Codec$</code></a></p>""")
     markdown("@scaladoc[scala.io package](scala.io.index)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/index.html" title="scala.io">scala.io package</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.12.0/scala/io/index.html" title="scala.io"><code>scala.io package</code></a></p>""")
   }
 
   it should "support Scala 2.11 links" in {
@@ -103,11 +103,11 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
       "scaladoc.version" -> "2.11.12")
 
     markdown("@scaladoc[Int](scala.Int)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/Int.html" title="scala.Int">Int</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/Int.html" title="scala.Int"><code>Int</code></a></p>""")
     markdown("@scaladoc[Codec$](scala.io.Codec$)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/io/Codec$.html" title="scala.io.Codec">Codec$</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/io/Codec$.html" title="scala.io.Codec"><code>Codec$</code></a></p>""")
     markdown("@scaladoc[scala.io package](scala.io.package)") shouldEqual
-      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/io/package.html" title="scala.io">scala.io package</a></p>""")
+      html("""<p><a href="http://www.scala-lang.org/api/2.11.12/scala/io/package.html" title="scala.io"><code>scala.io package</code></a></p>""")
   }
 
   it should "support referenced links" in {
@@ -116,6 +116,6 @@ class ScaladocDirectiveSpec extends MarkdownBaseSpec {
         |
         |  [1]: org.example.Model
       """) shouldEqual
-      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model">Model</a> spec</p>""")
+      html("""<p>The <a href="http://example.org/api/0.1.2/org/example/Model.html" title="org.example.Model"><code>Model</code></a> spec</p>""")
   }
 }