Support link to methods with bounded types (#130)

* Adds test exercising the issue
* Test and document bounded types. 
* Bonus: document higher-order functions
* Adds a suggestion to fix the error on the error message

Author: ignasi35

README.md

@@ -91,6 +91,21 @@ produce an unambigious result, you will have to use the FQCN.
     * Scala: method - `akka/stream/scaladsl/Flow.html#method():Unit`
     * Java: method - `akka/stream/javadsl/Flow.html#method()`
 
+* `@apidoc[method](Flow) { scala="#method[T]():Unit" java="#method()" }` (Link to method anchors.)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: method - `akka/stream/scaladsl/Flow.html#method[T]():Unit`
+    * Java: method - `akka/stream/javadsl/Flow.html#method()`
+
+* `@apidoc[method](Flow) { scala="#method%5BT%3C:S]():Unit" java="#method()" }` (Link to method anchors. Where the method has type bounds.)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: method - `akka/stream/scaladsl/Flow.html#method[T<:S]():Unit`
+    * Java: method - `akka/stream/javadsl/Flow.html#method()`
+
+* `@apidoc[method](Flow) { scala="#method(String=%3EInt):Unit" java="#method()" }` (Link to method anchors. Using higher-order function arguments)
+    * classes: `akka.stream.scaladsl.Flow` - `akka.stream.javadsl.Flow`
+    * Scala: method - `akka/stream/scaladsl/Flow.html#method(String=>Int):Unit`
+    * Java: method - `akka/stream/javadsl/Flow.html#method()`
+
 
 ### When only Scaladoc is generated
 

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

@@ -16,6 +16,9 @@
 
 package com.lightbend.paradox.apidoc
 
+import com.lightbend.paradox.ParadoxError
+import com.lightbend.paradox.ParadoxException
+import com.lightbend.paradox.markdown.{Url => ParadoxUrl}
 import com.lightbend.paradox.markdown.{InlineDirective, Writer}
 import org.pegdown.Printer
 import org.pegdown.ast.DirectiveNode.Source
@@ -149,6 +152,23 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Cont
       node: DirectiveNode
   ): DirectiveNode = {
     val attributes = new org.pegdown.ast.DirectiveAttributes.AttributeMap()
+    val theUrl     = fqcn + anchor
+    try {
+      ParadoxUrl(theUrl)
+    } catch {
+      case ParadoxUrl.Error(reason) =>
+        val suggestedUrl = theUrl
+          .replace("<", "%3C")
+          .replace(">", "%3E")
+          .replace("[", "%5B")
+        throw new ParadoxException(
+          ParadoxError(
+            s"$reason. Try percent-encoding manually some of the reserved characters, for example: [$suggestedUrl]. See https://github.com/lightbend/sbt-paradox-apidoc/pull/130 for more details.",
+            None,
+            None
+          )
+        )
+    }
     new DirectiveNode(
       DirectiveNode.Format.Inline,
       group,
@@ -160,7 +180,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Cont
         DirectiveNode.Format.Inline,
         doctype + "doc",
         label,
-        new DirectiveNode.Source.Direct(fqcn + anchor),
+        new DirectiveNode.Source.Direct(theUrl),
         node.attributes,
         label, // contents
         null

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

@@ -16,6 +16,8 @@
 
 package com.lightbend.paradox.apidoc
 
+import java.io.IOException
+
 import com.lightbend.paradox.ParadoxException
 import com.lightbend.paradox.markdown.Writer
 
@@ -284,4 +286,31 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
           |thingie</p>""".stripMargin
       )
   }
+
+  it should "use anchors for methods with scala bounded types" in {
+    markdown(
+      """The @apidoc[label](Flow) { scala="#method%5BT%3C:Q[T]](Flow=%3EUnit):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>label</code></a></span><span class="group-scala">
+          |<a href="https://doc.akka.io/api/akka/2.5/akka/stream/scaladsl/Flow.html#method[T%3C:Q[T]](Flow=%3EUnit):Unit" title="akka.stream.scaladsl.Flow"><code>label</code></a></span>
+          |thingie</p>""".stripMargin
+      )
+  }
+
+  it should "catch exception on malformed URIs and make suggestions" in {
+    try {
+
+      markdown(
+        """The @apidoc[label](Flow) { scala="#method[ T <: Q[T] ](Flow => Unit):Unit"  java="#method()" } thingie"""
+      )
+    } catch {
+      case t @ ParadoxException(error) => {
+        error.msg should include("template resulted in an invalid URL")
+        error.msg should include("method%5B T %3C: Q%5BT] ](Flow =%3E Unit):Unit")
+      }
+    }
+  }
+
 }