Better errors (#88)

Author: raboof

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

@@ -17,14 +17,14 @@
 package com.lightbend.paradox.apidoc
 
 import com.lightbend.paradox.markdown.InlineDirective
+import com.lightbend.paradox.markdown.Writer
 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])
-    extends InlineDirective("apidoc") {
+class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Context) extends InlineDirective("apidoc") {
   final val JavadocProperty = raw"""javadoc\.(.*)\.base_url""".r
-  final val JavadocBaseUrls = properties.collect {
+  final val JavadocBaseUrls = ctx.properties.collect {
     case (JavadocProperty(pkg), url) => pkg -> url
   }
 
@@ -86,7 +86,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
             val regex = (query.pattern.replaceAll("\\.", "\\\\.").replaceAll("\\*", ".*") + "$").r
             allClasses.filter(cls => regex.findFirstMatchIn(cls).isDefined) match {
               case Seq() =>
-                throw new java.lang.IllegalStateException(s"Class not found for @apidoc[$query]")
+                ctx.error(s"Class not found for @apidoc[$query]", node)
               case results =>
                 renderMatches(query, results, node, visitor, printer)
             }
@@ -139,9 +139,12 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
 
     matches.size match {
       case 0 =>
-        throw new java.lang.IllegalStateException(s"No matches found for $query")
+        ctx.error(s"No matches found for apidoc query [$query]", node)
       case 1 if matches(0).contains("adsl") =>
-        throw new java.lang.IllegalStateException(s"Match for $query only found in one language: ${matches(0)}")
+        ctx.error(
+          s"Match for apidoc query [$query] only found in one language: ${matches(0)}",
+          node
+        )
       case 1 =>
         val pkg = matches(0)
         syntheticNode("scala", "scala", query.scalaLabel(pkg), pkg + scalaClassSuffix, sAnchor, node).accept(visitor)
@@ -163,9 +166,10 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], properties: Map[
           }
         })
       case n =>
-        throw new java.lang.IllegalStateException(
+        ctx.error(
           s"$n matches found for $query, but not javadsl/scaladsl: ${matches.mkString(", ")}. " +
-              s"You may want to use the fully qualified class name as @apidoc[fqcn] instead of @apidoc[$query]."
+              s"You may want to use the fully qualified class name as @apidoc[fqcn] instead of @apidoc[$query].",
+          node
         )
     }
   }

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

@@ -55,7 +55,7 @@ object ApidocPlugin extends AutoPlugin {
           Def.task {
             Seq(
               { ctx: Writer.Context =>
-                new ApidocDirective(allClasses, ctx.properties)
+                new ApidocDirective(allClasses, ctx)
               }
             )
           }

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

@@ -16,6 +16,7 @@
 
 package com.lightbend.paradox.apidoc
 
+import com.lightbend.paradox.ParadoxException
 import com.lightbend.paradox.markdown.Writer
 
 class ApidocDirectiveSpec extends MarkdownBaseSpec {
@@ -53,7 +54,7 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
     verbatimSerializers = Writer.defaultVerbatims,
     serializerPlugins = Writer.defaultPlugins(
       Writer.defaultDirectives ++ Seq(
-            (ctx: Writer.Context) => new ApidocDirective(allClasses, ctx.properties)
+            (ctx: Writer.Context) => new ApidocDirective(allClasses, ctx)
           )
     )
   )
@@ -77,9 +78,9 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
   }
 
   it should "throw an exception when there is no match" in {
-    val thrown = the[IllegalStateException] thrownBy markdown("@apidoc[ThereIsNoSuchClass]")
+    val thrown = the[ParadoxException] thrownBy markdown("@apidoc[ThereIsNoSuchClass]")
     thrown.getMessage shouldEqual
-      "No matches found for ThereIsNoSuchClass"
+      "No matches found for apidoc query [ThereIsNoSuchClass]"
   }
 
   it should "generate markdown correctly when 2 matches found and their package names include javadsl/scaladsl" in {
@@ -113,7 +114,7 @@ class ApidocDirectiveSpec extends MarkdownBaseSpec {
   }
 
   it should "throw an exception when two matches found but javadsl/scaladsl is not in their packages" in {
-    val thrown = the[IllegalStateException] thrownBy markdown("@apidoc[ActorRef]")
+    val thrown = the[ParadoxException] thrownBy markdown("@apidoc[ActorRef]")
     thrown.getMessage shouldEqual
       "2 matches found for ActorRef, but not javadsl/scaladsl: akka.actor.ActorRef, akka.actor.typed.ActorRef. You may want to use the fully qualified class name as @apidoc[fqcn] instead of @apidoc[ActorRef]."
   }