Detect link to class (where object is intended) (#155)

* Detect link to class (where object is intended)

* Quilify forwarding only classes more

Author: ennru

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

@@ -20,20 +20,38 @@ 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 io.github.classgraph.ScanResult
 import org.pegdown.Printer
 import org.pegdown.ast.DirectiveNode.Source
 import org.pegdown.ast.{DirectiveNode, Visitor}
 
+import scala.collection.JavaConverters._
+
 import scala.util.matching.Regex
 
-class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Context) extends InlineDirective("apidoc") {
+class ApidocDirective(scanner: ScanResult, allClassesAndObjects: IndexedSeq[String], ctx: Writer.Context)
+    extends InlineDirective("apidoc") {
   final val JavadocProperty = raw"""javadoc\.(.*)\.base_url""".r
   final val JavadocBaseUrls = ctx.properties.collect {
     case (JavadocProperty(pkg), url) => pkg -> url
   }
 
   val allClasses = allClassesAndObjects.filterNot(_.endsWith("$"))
 
+  def containsOnlyStaticForwarders(className: String): Boolean = {
+    val info = scanner.getClassInfo(className)
+    info != null && info.isFinal && info.getMethodInfo.asScala.forall(_.isStatic)
+  }
+
+  private def errorForStaticForwardersOnly(query: Query, node: DirectiveNode, classname: String) =
+    if (!query.linkToObject && containsOnlyStaticForwarders(classname) &&
+        allClassesAndObjects.contains(classname + "$")) {
+      ctx.error(
+        s"Class `$classname` matches @apidoc[$query], but is empty, did you intend to link to the object?",
+        node
+      )
+    }
+
   private case class Query(label: Option[String], pattern: String, generics: String, linkToObject: Boolean) {
     def scalaLabel(matched: String): String =
       label match {
@@ -111,10 +129,11 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Cont
             renderMatches(query, results, node, visitor, printer)
         }
       }
-    } else {
+    } else { // only a classname
       val className    = '.' + query.pattern
       val classMatches = allClasses.filter(_.endsWith(className))
       if (classMatches.size == 1 && classMatches(0).contains(".javadsl.")) {
+        errorForStaticForwardersOnly(query, node, classMatches(0))
         val objectName = className + '$'
         val allMatches = allClassesAndObjects.filter(name => name.endsWith(className) || name.endsWith(objectName))
         renderMatches(query, allMatches, node, visitor, printer)
@@ -209,6 +228,7 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Cont
         )
       case 1 =>
         val pkg = matches(0)
+        errorForStaticForwardersOnly(query, node, query.scalaFqcn(pkg))
         scaladocNode("scala", query.scalaLabel(pkg), query.scalaFqcn(pkg) + scalaClassSuffix, sAnchor, node)
           .accept(visitor)
         if (hasJavadocUrl(pkg)) {
@@ -218,9 +238,11 @@ class ApidocDirective(allClassesAndObjects: IndexedSeq[String], ctx: Writer.Cont
             .accept(visitor)
       case 2 if matches.forall(_.contains("adsl")) =>
         matches.foreach { pkg =>
-          if (!pkg.contains("javadsl"))
+          if (!pkg.contains("javadsl")) {
+            errorForStaticForwardersOnly(query, node, query.scalaFqcn(pkg))
             scaladocNode("scala", query.scalaLabel(pkg), query.scalaFqcn(pkg) + scalaClassSuffix, sAnchor, node)
               .accept(visitor)
+          }
           if (!pkg.contains("scaladsl")) {
             if (hasJavadocUrl(pkg))
               javadocNode(query.javaLabel(pkg), query.javaFqcn(pkg), jAnchor, node).accept(visitor)

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

@@ -50,10 +50,11 @@ object ApidocPlugin extends AutoPlugin {
           val scanner = new ClassGraph()
             .whitelistPackages(apidocRootPackage.value)
             .addClassLoader(classLoader)
+            .enableMethodInfo()
             .scan()
           val allClasses = scanner.getAllClasses.getNames.asScala.toVector
           Def.task {
-            Seq((ctx: Writer.Context) => new ApidocDirective(allClasses, ctx))
+            Seq((ctx: Writer.Context) => new ApidocDirective(scanner, allClasses, ctx))
           }
         }.value
   )

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

@@ -1,3 +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" title="akka.stream.javadsl.Flow"><code>Flow</code></a></span><span class="group-scala"><a href="akka-stream-scaladoc/akka/stream/scaladsl/Flow.html" title="akka.stream.scaladsl.Flow"><code>Flow</code></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" title="akka.stream.stage.GraphStage"><code>GraphStage</code></a></span><span class="group-java"><a href="akka-stream-scaladoc/akka/stream/stage/GraphStage.html" title="akka.stream.stage.GraphStage"><code>GraphStage</code></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" title="akka.actor.typed.javadsl.Behaviors"><code>Behaviors</code></a></span><span class="group-scala"><a href="akka-scaladoc/akka/actor/typed/scaladsl/Behaviors.html" title="akka.actor.typed.scaladsl.Behaviors"><code>Behaviors</code></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" title="akka.actor.typed.javadsl.Behaviors"><code>Behaviors</code></a></span><span class="group-scala"><a href="akka-scaladoc/akka/actor/typed/scaladsl/Behaviors$.html" title="akka.actor.typed.scaladsl.Behaviors"><code>Behaviors</code></a></span></p>

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

@@ -2,4 +2,4 @@ Api link to a class that is both in scaladsl and javadsl packages, but has no ja
 
 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]
+Api link to a class that is both in scaladsl and javadsl packages, and has javadoc configured: @apidoc[Behaviors$]

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

@@ -20,14 +20,14 @@ import java.io.IOException
 
 import com.lightbend.paradox.ParadoxException
 import com.lightbend.paradox.markdown.{MarkdownTestkit, Writer}
-
+import io.github.classgraph.ScanResult
 import org.scalatest.matchers.should.Matchers
 import org.scalatest.flatspec.AnyFlatSpecLike
 
 class ApidocDirectiveSpec extends MarkdownTestkit with Matchers with AnyFlatSpecLike {
   val rootPackage = "akka"
 
-  val allClasses = Array(
+  val allClasses = Vector(
     "akka.actor.ActorRef",
     "akka.actor.typed.ActorRef",
     "akka.cluster.client.ClusterClient",
@@ -54,6 +54,12 @@ class ApidocDirectiveSpec extends MarkdownTestkit with Matchers with AnyFlatSpec
     "akka.stream.scaladsl.Flow$",
     "akka.stream.scaladsl.JavaFlowSupport$",
     "akka.stream.javadsl.JavaFlowSupport",
+    "akka.kafka.Metadata",
+    "akka.kafka.Metadata$",
+    "akka.kafka.javadsl.Producer",
+    "akka.kafka.javadsl.Producer$",
+    "akka.kafka.scaladsl.Producer",
+    "akka.kafka.scaladsl.Producer$",
     "akka.kafka.scaladsl.Consumer$Control",
     "akka.kafka.javadsl.Consumer$Control",
     "akka.kafka.scaladsl.Consumer$Control$$anonfun$drainAndShutdown$2",
@@ -64,7 +70,13 @@ class ApidocDirectiveSpec extends MarkdownTestkit with Matchers with AnyFlatSpec
     linkRenderer        = Writer.defaultLinks,
     verbatimSerializers = Writer.defaultVerbatims,
     serializerPlugins = Writer.defaultPlugins(
-      Writer.defaultDirectives ++ Seq((ctx: Writer.Context) => new ApidocDirective(allClasses, ctx))
+      Writer.defaultDirectives ++ Seq((ctx: Writer.Context) =>
+            new ApidocDirective(null: ScanResult, allClasses, ctx) {
+              override def containsOnlyStaticForwarders(classname: String): Boolean =
+                "akka.kafka.Metadata" == classname ||
+                  "akka.kafka.scaladsl.Producer" == classname
+            }
+          )
     )
   )
 
@@ -94,6 +106,24 @@ class ApidocDirectiveSpec extends MarkdownTestkit with Matchers with AnyFlatSpec
       "No matches found for apidoc query [ThereIsNoSuchClass]"
   }
 
+  it should "fail when pointing to a static-forwarders-only class" in {
+    val thrown = the[ParadoxException] thrownBy markdown("@apidoc[Metadata]")
+    thrown.getMessage shouldEqual
+      "Class `akka.kafka.Metadata` matches @apidoc[Metadata], but is empty, did you intend to link to the object?"
+  }
+
+  it should "fail when pointing to a static-forwarders-only class (in scaladsl/javadsl)" in {
+    val thrown = the[ParadoxException] thrownBy markdown("@apidoc[Producer]")
+    thrown.getMessage shouldEqual
+      "Class `akka.kafka.scaladsl.Producer` matches @apidoc[Producer], but is empty, did you intend to link to the object?"
+  }
+
+  it should "fail when pointing to a static-forwarders-only class (with pattern)" in {
+    val thrown = the[ParadoxException] thrownBy markdown("@apidoc[akka.kafka.(java|scala)dsl.Producer]")
+    thrown.getMessage shouldEqual
+      "Class `akka.kafka.scaladsl.Producer` matches @apidoc[akka.kafka.(java|scala)dsl.Producer], but is empty, did you intend to link to the object?"
+  }
+
   it should "generate markdown correctly when 2 matches found and their package names include javadsl/scaladsl" in {
     markdown("@apidoc[Flow]") shouldEqual
       html(