Dedicated scalaDoc plugins and options (#433)

* Dedicated scalaDoc plugins and options

* Use T{} for consistency

2 files changed, 111 insertions, 7 deletions

diff --git a/scalalib/src/mill/scalalib/ScalaModule.scala b/scalalib/src/mill/scalalib/ScalaModule.scala
index 8c7d40fc..3a4a9d45 100644
--- a/scalalib/src/mill/scalalib/ScalaModule.scala
+++ b/scalalib/src/mill/scalalib/ScalaModule.scala
@@ -3,8 +3,7 @@ package scalalib
 
 import ammonite.ops._
 import coursier.Repository
-import mill.define.Task
-import mill.define.TaskModule
+import mill.define.{Target, Task, TaskModule}
 import mill.eval.{PathRef, Result}
 import mill.modules.Jvm
 import mill.modules.Jvm.{createJar, subprocess}
@@ -62,8 +61,12 @@ trait ScalaModule extends JavaModule { outer =>
 
   def scalacPluginIvyDeps = T{ Agg.empty[Dep] }
 
+  def scalaDocPluginIvyDeps = T{ scalacPluginIvyDeps() }
+
   def scalacOptions = T{ Seq.empty[String] }
 
+  def scalaDocOptions = T{ scalacOptions() }
+
   private val Milestone213 = raw"""2.13.(\d+)-M(\d+)""".r
 
   def scalaCompilerBridgeSources = T {
@@ -99,6 +102,10 @@ trait ScalaModule extends JavaModule { outer =>
     resolveDeps(scalacPluginIvyDeps)()
   }
 
+  def scalaDocPluginClasspath: T[Agg[PathRef]] = T {
+    resolveDeps(scalaDocPluginIvyDeps)()
+  }
+
   def scalaLibraryIvyDeps = T{ scalaRuntimeIvyDeps(scalaOrganization(), scalaVersion()) }
   /**
     * Classpath of the Scala Compiler & any compiler plugins
@@ -149,8 +156,8 @@ trait ScalaModule extends JavaModule { outer =>
       if (p.isFile && ((p.ext == "scala") || (p.ext == "java")))
     } yield p.toNIO.toString
 
-    val pluginOptions = scalacPluginClasspath().map(pluginPathRef => s"-Xplugin:${pluginPathRef.path}")
-    val options = Seq("-d", javadocDir.toNIO.toString, "-usejavacp") ++ pluginOptions ++ scalacOptions()
+    val pluginOptions = scalaDocPluginClasspath().map(pluginPathRef => s"-Xplugin:${pluginPathRef.path}")
+    val options = Seq("-d", javadocDir.toNIO.toString, "-usejavacp") ++ pluginOptions ++ scalaDocOptions()
 
     if (files.nonEmpty) subprocess(
       "scala.tools.nsc.ScalaDoc",
diff --git a/scalalib/test/src/mill/scalalib/HelloWorldTests.scala b/scalalib/test/src/mill/scalalib/HelloWorldTests.scala
index e1ac8bb7..ed77216d 100644
--- a/scalalib/test/src/mill/scalalib/HelloWorldTests.scala
+++ b/scalalib/test/src/mill/scalalib/HelloWorldTests.scala
@@ -5,6 +5,7 @@ import java.util.jar.JarFile
 import ammonite.ops._
 import mill._
 import mill.define.Target
+import mill.eval.Result.Exception
 import mill.eval.{Evaluator, Result}
 import mill.modules.Assembly
 import mill.scalalib.publish._
@@ -139,17 +140,36 @@ object HelloWorldTests extends TestSuite {
     object model extends HelloWorldModule
   }
 
-  object HelloWorldWarnUnused extends HelloBase{
+  object HelloWorldWarnUnused extends HelloBase {
     object core extends HelloWorldModule {
       def scalacOptions = T(Seq("-Ywarn-unused"))
     }
   }
 
-  object HelloWorldFatalWarnings extends HelloBase{
+  object HelloWorldFatalWarnings extends HelloBase {
     object core extends HelloWorldModule {
       def scalacOptions = T(Seq("-Ywarn-unused", "-Xfatal-warnings"))
     }
+  }
+
+  object HelloWorldWithDocVersion extends HelloBase {
+    object core extends HelloWorldModule {
+      def scalacOptions = T(Seq("-Ywarn-unused", "-Xfatal-warnings"))
+      def scalaDocOptions = super.scalaDocOptions() ++ Seq("-doc-version", "1.2.3")
+    }
+  }
+
+  object HelloWorldOnlyDocVersion extends HelloBase {
+    object core extends HelloWorldModule {
+      def scalacOptions = T(Seq("-Ywarn-unused", "-Xfatal-warnings"))
+      def scalaDocOptions = T(Seq("-doc-version", "1.2.3"))
+    }
+  }
 
+  object HelloWorldDocTitle extends HelloBase {
+    object core extends HelloWorldModule {
+      def scalaDocOptions = T(Seq("-doc-title", "Hello World"))
+    }
   }
 
   object HelloWorldWithPublish extends HelloBase{
@@ -199,6 +219,9 @@ object HelloWorldTests extends TestSuite {
       def scalacPluginIvyDeps = super.scalacPluginIvyDeps() ++ Agg(
         ivy"org.scalamacros:::paradise:2.1.0"
       )
+      def scalaDocPluginIvyDeps = super.scalaDocPluginIvyDeps() ++ Agg(
+        ivy"com.typesafe.genjavadoc:::genjavadoc-plugin:0.11"
+      )
     }
   }
 
@@ -323,6 +346,81 @@ object HelloWorldTests extends TestSuite {
       }
     }
 
+    'scalaDocOptions - {
+      'emptyByDefault - workspaceTest(HelloWorld){eval =>
+        val Right((result, evalCount)) = eval.apply(HelloWorld.core.scalaDocOptions)
+        assert(
+          result.isEmpty,
+          evalCount > 0
+        )
+      }
+      'override - workspaceTest(HelloWorldDocTitle){ eval =>
+        val Right((result, evalCount)) = eval.apply(HelloWorldDocTitle.core.scalaDocOptions)
+        assert(
+          result == Seq("-doc-title", "Hello World"),
+          evalCount > 0
+        )
+      }
+      'extend - workspaceTest(HelloWorldWithDocVersion){ eval =>
+        val Right((result, evalCount)) = eval.apply(HelloWorldWithDocVersion.core.scalaDocOptions)
+        assert(
+          result == Seq("-Ywarn-unused", "-Xfatal-warnings", "-doc-version", "1.2.3"),
+          evalCount > 0
+        )
+      }
+      // make sure options are passed during ScalaDoc generation
+      'docJarWithTitle - workspaceTest(
+        HelloWorldDocTitle,
+        resourcePath = pwd / 'scalalib / 'test / 'resources / "hello-world"
+      ){ eval =>
+        val Right((_, evalCount)) = eval.apply(HelloWorldDocTitle.core.docJar)
+        assert(
+          evalCount > 0,
+          read(eval.outPath / 'core / 'docJar / 'dest / 'javadoc / "index.html").contains("<span id=\"doc-title\">Hello World")
+        )
+      }
+      'docJarWithVersion - workspaceTest(
+        HelloWorldWithDocVersion,
+        resourcePath = pwd / 'scalalib / 'test / 'resources / "hello-world"
+      ){ eval =>
+        // scaladoc generation fails because of "-Xfatal-warnings" flag
+        val Left(Result.Exception(InteractiveShelloutException(), outerStack)) = eval.apply(HelloWorldWithDocVersion.core.docJar)
+      }
+      'docJarOnlyVersion - workspaceTest(
+        HelloWorldOnlyDocVersion,
+        resourcePath = pwd / 'scalalib / 'test / 'resources / "hello-world"
+      ){ eval =>
+        val Right((_, evalCount)) = eval.apply(HelloWorldOnlyDocVersion.core.docJar)
+        assert(
+          evalCount > 0,
+          read(eval.outPath / 'core / 'docJar / 'dest / 'javadoc / "index.html").contains("<span id=\"doc-version\">1.2.3")
+        )
+      }
+    }
+
+    'scalacPluginClasspath - {
+      'withMacroParadise - workspaceTest(HelloWorldTypeLevel){eval =>
+        val Right((result, evalCount)) = eval.apply(HelloWorldTypeLevel.foo.scalacPluginClasspath)
+        assert(
+          result.nonEmpty,
+          result.exists { pathRef => pathRef.path.segments.contains("scalamacros") },
+          evalCount > 0
+        )
+      }
+    }
+
+    'scalaDocPluginClasspath - {
+      'extend - workspaceTest(HelloWorldTypeLevel){eval =>
+        val Right((result, evalCount)) = eval.apply(HelloWorldTypeLevel.foo.scalaDocPluginClasspath)
+        assert(
+          result.nonEmpty,
+          result.exists { pathRef => pathRef.path.segments.contains("scalamacros") },
+          result.exists { pathRef => pathRef.path.segments.contains("genjavadoc") },
+          evalCount > 0
+        )
+      }
+    }
+
     'compile - {
       'fromScratch - workspaceTest(HelloWorld){eval =>
         val Right((result, evalCount)) = eval.apply(HelloWorld.core.compile)
@@ -380,7 +478,6 @@ object HelloWorldTests extends TestSuite {
       'passScalacOptions - workspaceTest(HelloWorldFatalWarnings){ eval =>
         // compilation fails because of "-Xfatal-warnings" flag
         val Left(Result.Failure("Compilation failed", _)) = eval.apply(HelloWorldFatalWarnings.core.compile)
-
       }
     }