Handle arguments properly

Use compiler reporter and provide our reporter for dokka
Refactor how we handle arguments
Unify sbt and cmd way to run documentation

Author: romanowski

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -7,8 +7,8 @@ import PathResolver.Defaults
 import rewrites.Rewrites
 import Settings.Setting
 
-class ScalaSettings extends Settings.SettingGroup {
-
+/** Settings shared by compiler and scala3doc */
+trait CommonScalaSettings { self: Settings.SettingGroup =>
   protected def defaultClasspath: String = sys.env.getOrElse("CLASSPATH", ".")
 
   /** Path related settings */
@@ -18,33 +18,76 @@ class ScalaSettings extends Settings.SettingGroup {
   val javaextdirs: Setting[String] = PathSetting("-javaextdirs", "Override java extdirs classpath.", Defaults.javaExtDirs) withAbbreviation "--java-extension-directories"
   val sourcepath: Setting[String] = PathSetting("-sourcepath", "Specify location(s) of source files.", Defaults.scalaSourcePath) withAbbreviation "--source-path"
   val sourceroot: Setting[String] = PathSetting("-sourceroot", "Specify workspace root directory.", ".")
-  val semanticdbTarget: Setting[String] = PathSetting("-semanticdb-target", "Specify an alternative output directory for SemanticDB files.", "")
 
   val classpath: Setting[String] = PathSetting("-classpath", "Specify where to find user class files.", defaultClasspath) withAbbreviation "-cp" withAbbreviation "--class-path"
   val outputDir: Setting[AbstractFile] = OutputSetting("-d", "directory|jar", "Destination for generated classfiles.",
     new PlainDirectory(Directory(".")))
   val priorityclasspath: Setting[String] = PathSetting("-priorityclasspath", "Class path that takes precedence over all other paths (or testing only).", "") withAbbreviation "--priority-class-path"
+  val color: Setting[String] = ChoiceSetting("-color", "mode", "Colored output", List("always", "never"/*, "auto"*/), "always"/* "auto"*/) withAbbreviation "--color"
+  val verbose: Setting[Boolean] = BooleanSetting("-verbose", "Output messages about what the compiler is doing.") withAbbreviation "--verbose"
+  val version: Setting[Boolean] = BooleanSetting("-version", "Print product version and exit.") withAbbreviation "--version"
+  val pageWidth: Setting[Int] = IntSetting("-pagewidth", "Set page width", 80) withAbbreviation "--page-width"
+  val silentWarnings: Setting[Boolean] = BooleanSetting("-nowarn", "Silence all warnings.") withAbbreviation "--no-warnings"
 
   /** Other settings */
-  val deprecation: Setting[Boolean] = BooleanSetting("-deprecation", "Emit warning and location for usages of deprecated APIs.") withAbbreviation "--deprecation"
   val encoding: Setting[String] = StringSetting("-encoding", "encoding", "Specify character encoding used by source files.", Properties.sourceEncoding) withAbbreviation "--encoding"
+  val usejavacp: Setting[Boolean] = BooleanSetting("-usejavacp", "Utilize the java.class.path in classpath resolution.") withAbbreviation "--use-java-class-path"
+
+  /** Plugin-related setting */
+  val plugin: Setting[List[String]]             = MultiStringSetting  ("-Xplugin", "paths", "Load a plugin from each classpath.")
+  val disable: Setting[List[String]]            = MultiStringSetting  ("-Xplugin-disable", "plugin", "Disable plugins by name.")
+  val require: Setting[List[String]]            = MultiStringSetting  ("-Xplugin-require", "plugin", "Abort if a named plugin is not loaded.")
+  val showPlugins: Setting[Boolean]        = BooleanSetting      ("-Xplugin-list", "Print a synopsis of loaded plugins.")
+  val pluginsDir: Setting[String]         = StringSetting       ("-Xpluginsdir", "path", "Path to search for plugin archives.", Defaults.scalaPluginPath)
+  val pluginOptions: Setting[List[String]]      = MultiStringSetting  ("-P", "plugin:opt", "Pass an option to a plugin, e.g. -P:<plugin>:<opt>")
+
+   /** Doctool specific settings */
+  val siteRoot: Setting[String] = StringSetting(
+    "-siteroot",
+    "site root",
+    "A directory containing static files from which to generate documentation.",
+    "./docs"
+  )
+
+
+  val projectName: Setting[String] = StringSetting (
+    "-project",
+    "project title",
+    "The name of the project.",
+    ""
+  )
+
+  val projectVersion: Setting[String] = StringSetting (
+    "-project-version",
+    "project version",
+    "The current version of your project.",
+    ""
+  )
+
+  val projectLogo: Setting[String] = StringSetting(
+    "-project-logo",
+    "project logo filename",
+    "The file that contains the project's logo (in /images).",
+    ""
+  )
+}
+
+class ScalaSettings extends Settings.SettingGroup with CommonScalaSettings {
+  /** Path related settings */
+  val semanticdbTarget: Setting[String] = PathSetting("-semanticdb-target", "Specify an alternative output directory for SemanticDB files.", "")
+
+  val deprecation: Setting[Boolean] = BooleanSetting("-deprecation", "Emit warning and location for usages of deprecated APIs.") withAbbreviation "--deprecation"
   val explainTypes: Setting[Boolean] = BooleanSetting("-explain-types", "Explain type errors in more detail.") withAbbreviation "--explain-types"
   val explain: Setting[Boolean] = BooleanSetting("-explain", "Explain errors in more detail.") withAbbreviation "--explain"
   val feature: Setting[Boolean] = BooleanSetting("-feature", "Emit warning and location for usages of features that should be imported explicitly.") withAbbreviation "--feature"
   val help: Setting[Boolean] = BooleanSetting("-help", "Print a synopsis of standard options.") withAbbreviation "--help"
-  val color: Setting[String] = ChoiceSetting("-color", "mode", "Colored output", List("always", "never"/*, "auto"*/), "always"/* "auto"*/) withAbbreviation "--color"
   val source: Setting[String] = ChoiceSetting("-source", "source version", "source version", List("3.0", "3.1", "3.0-migration", "3.1-migration"), "3.0").withAbbreviation("--source")
   val target: Setting[String] = ChoiceSetting("-target", "target", "Target platform for object files.", List("jvm-1.8", "jvm-9"), "jvm-1.8") withAbbreviation "--target"
   val scalajs: Setting[Boolean] = BooleanSetting("-scalajs", "Compile in Scala.js mode (requires scalajs-library.jar on the classpath).") withAbbreviation "--scalajs"
   val unchecked: Setting[Boolean] = BooleanSetting("-unchecked", "Enable additional warnings where generated code depends on assumptions.") withAbbreviation "--unchecked"
   val uniqid: Setting[Boolean] = BooleanSetting("-uniqid", "Uniquely tag all identifiers in debugging output.") withAbbreviation "--unique-id"
-  val usejavacp: Setting[Boolean] = BooleanSetting("-usejavacp", "Utilize the java.class.path in classpath resolution.") withAbbreviation "--use-java-class-path"
-  val verbose: Setting[Boolean] = BooleanSetting("-verbose", "Output messages about what the compiler is doing.") withAbbreviation "--verbose"
-  val version: Setting[Boolean] = BooleanSetting("-version", "Print product version and exit.") withAbbreviation "--version"
-  val pageWidth: Setting[Int] = IntSetting("-pagewidth", "Set page width", 80) withAbbreviation "--page-width"
   val language: Setting[List[String]] = MultiStringSetting("-language", "feature", "Enable one or more language features.") withAbbreviation "--language"
   val rewrite: Setting[Option[Rewrites]] = OptionSetting[Rewrites]("-rewrite", "When used in conjunction with a `...-migration` source version, rewrites sources to migrate to new version.") withAbbreviation "--rewrite"
-  val silentWarnings: Setting[Boolean] = BooleanSetting("-nowarn", "Silence all warnings.") withAbbreviation "--no-warnings"
   val fromTasty: Setting[Boolean] = BooleanSetting("-from-tasty", "Compile classes from tasty files. The arguments are .tasty or .jar files.") withAbbreviation "--from-tasty"
 
   val newSyntax: Setting[Boolean] = BooleanSetting("-new-syntax", "Require `then` and `do` in control expressions.")
@@ -57,20 +100,11 @@ class ScalaSettings extends Settings.SettingGroup {
   val printTasty: Setting[Boolean] = BooleanSetting("-print-tasty", "Prints the raw tasty.") withAbbreviation "--print-tasty"
   val printLines: Setting[Boolean] = BooleanSetting("-print-lines", "Show source code line numbers.") withAbbreviation "--print-lines"
 
-  /** Plugin-related setting */
-  val plugin: Setting[List[String]]             = MultiStringSetting  ("-Xplugin", "paths", "Load a plugin from each classpath.")
-  val disable: Setting[List[String]]            = MultiStringSetting  ("-Xplugin-disable", "plugin", "Disable plugins by name.")
-  val require: Setting[List[String]]            = MultiStringSetting  ("-Xplugin-require", "plugin", "Abort if a named plugin is not loaded.")
-  val showPlugins: Setting[Boolean]        = BooleanSetting      ("-Xplugin-list", "Print a synopsis of loaded plugins.")
-  val pluginsDir: Setting[String]         = StringSetting       ("-Xpluginsdir", "path", "Path to search for plugin archives.", Defaults.scalaPluginPath)
-  val pluginOptions: Setting[List[String]]      = MultiStringSetting  ("-P", "plugin:opt", "Pass an option to a plugin, e.g. -P:<plugin>:<opt>")
-
   /** Scala.js-related settings */
   val scalajsGenStaticForwardersForNonTopLevelObjects: Setting[Boolean] = BooleanSetting("-scalajs-genStaticForwardersForNonTopLevelObjects", "Generate static forwarders even for non-top-level objects (Scala.js only)")
   val scalajsMapSourceURI: Setting[List[String]] = MultiStringSetting("-scalajs-mapSourceURI", "uri1[->uri2]", "rebases source URIs from uri1 to uri2 (or to a relative URI) for source maps (Scala.js only)")
 
-  /** -X "Advanced" settings
-   */
+  /** -X "Advanced" settings */
   val Xhelp: Setting[Boolean] = BooleanSetting("-X", "Print a synopsis of advanced options.")
   val XnoForwarders: Setting[Boolean] = BooleanSetting("-Xno-forwarders", "Do not generate static forwarders in mirror classes.")
   val XmaxInlines: Setting[Int] = IntSetting("-Xmax-inlines", "Maximal number of successive inlines.", 32)
@@ -186,28 +220,8 @@ class ScalaSettings extends Settings.SettingGroup {
   val Yinstrument: Setting[Boolean] = BooleanSetting("-Yinstrument", "Add instrumentation code that counts allocations and closure creations.")
   val YinstrumentDefs: Setting[Boolean] = BooleanSetting("-Yinstrument-defs", "Add instrumentation code that counts method calls; needs -Yinstrument to be set, too.")
 
-  /** Dottydoc specific settings */
-  val siteRoot: Setting[String] = StringSetting(
-    "-siteroot",
-    "site root",
-    "A directory containing static files from which to generate documentation.",
-    "./docs"
-  )
-
-
-  val projectName: Setting[String] = StringSetting (
-    "-project",
-    "project title",
-    "The name of the project.",
-    ""
-  )
-
-  val projectVersion: Setting[String] = StringSetting (
-    "-project-version",
-    "project version",
-    "The current version of your project.",
-    ""
-  )
+  /** Dottydoc specific settings that are not used in scala3doc */
+  val docSnapshot: Setting[Boolean] = BooleanSetting("-doc-snapshot", "Generate a documentation snapshot for the current Dotty version")
 
   val projectUrl: Setting[String] = StringSetting (
     "-project-url",
@@ -216,14 +230,5 @@ class ScalaSettings extends Settings.SettingGroup {
     ""
   )
 
-  val projectLogo: Setting[String] = StringSetting(
-    "-project-logo",
-    "project logo filename",
-    "The file that contains the project's logo (in /images).",
-    ""
-  )
-
-  val docSnapshot: Setting[Boolean] = BooleanSetting("-doc-snapshot", "Generate a documentation snapshot for the current Dotty version")
-
   val wikiSyntax: Setting[Boolean] = BooleanSetting("-Xwiki-syntax", "Retains the Scala2 behavior of using Wiki Syntax in Scaladoc.")
 }

project/Build.scala

@@ -1471,8 +1471,8 @@ object Build {
     def asScala3doc: Project = {
       def generateDocumentation(targets: String, name: String, outDir: String, ref: String, params: String = "") = Def.taskDyn {
           val projectVersion = version.value
-          val sourcesAndRevision = s"-s github://lampepfl/dotty  --revision $ref --projectVersion $projectVersion"
-          val cmd = s""" -d $outDir -n "$name" $sourcesAndRevision $params $targets"""
+          val sourcesAndRevision = s"-source-links github://lampepfl/dotty  -revision $ref -project-version $projectVersion"
+          val cmd = s""" -d $outDir -project "$name" $sourcesAndRevision $params $targets"""
           run.in(Compile).toTask(cmd)
       }
 
@@ -1511,7 +1511,7 @@ object Build {
             generateDocumentation(
               classDirectory.in(Compile).value.getAbsolutePath,
               "scala3doc", "scala3doc/output/self", VersionUtil.gitHash,
-              "-p scala3doc/documentation --projectLogo scala3doc/documentation/logo.svg")
+              "-siteroot scala3doc/documentation -project-logo scala3doc/documentation/logo.svg")
           }.value,
 
           generateScala3Documentation := Def.inputTaskDyn {
@@ -1535,7 +1535,7 @@ object Build {
               IO.write(dest / "CNAME", "dotty.epfl.ch")
             }.dependsOn(generateDocumentation(
               roots, "Scala 3", dest.getAbsolutePath, "master",
-              "-p scala3doc/scala3-docs --projectLogo scala3doc/scala3-docs/logo.svg"))
+              "-siteroot scala3doc/scala3-docs -project-logo scala3doc/scala3-docs/logo.svg"))
           }.evaluated,
 
 
@@ -1549,7 +1549,7 @@ object Build {
             if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
             else generateDocumentation(
               roots, "Scala 3", "scala3doc/output/scala3-stdlib", "maser",
-              "-p scala3doc/scala3-docs --syntax wiki --projectLogo scala3doc/scala3-docs/logo.svg "
+              "-siteroot scala3doc/scala3-docs -comment-syntax wiki -projec-logo scala3doc/scala3-docs/logo.svg "
             )
           }.value,
 

sbt-dotty/src/dotty/tools/sbtplugin/DottyPlugin.scala

@@ -19,6 +19,7 @@ object DottyPlugin extends AutoPlugin {
     val isDottyJS = settingKey[Boolean]("Is this project compiled with Dotty and Scala.js?")
 
     val useScala3doc = settingKey[Boolean]("Use Scala3doc as the documentation tool")
+    val tastyFiles = taskKey[Seq[File]]("List all testy files")
     val scala3docOptions = settingKey[Seq[String]]("Options for Scala3doc")
 
     // NOTE:
@@ -441,13 +442,15 @@ object DottyPlugin extends AutoPlugin {
   }
 
   private val docSettings = inTask(doc)(Seq(
+    tastyFiles := {
+      val _ = compile.value // Ensure that everything is compiled, so TASTy is available.
+      (classDirectory.value ** "*.tasty").get.map(_.getAbsoluteFile)
+    },
     sources := Def.taskDyn {
       val old = sources.value
 
       if (isDotty.value) Def.task {
-        val _ = compile.value // Ensure that everything is compiled, so TASTy is available.
-        val tastyFiles = (classDirectory.value ** "*.tasty").get.map(_.getAbsoluteFile)
-        old ++ tastyFiles
+        old ++ tastyFiles.value
       } else Def.task {
         old
       }

scala3doc/src/dotty/dokka/DottyDokkaConfig.scala

@@ -6,8 +6,8 @@ import java.io.File
 import collection.JavaConverters._
 import dotty.dokka.site.StaticSiteContext
 
-case class DottyDokkaConfig(docConfiguration: DocConfiguration) extends DokkaConfiguration:
-  override def getOutputDir: File = docConfiguration.args.output
+case class DottyDokkaConfig(args: Scala3doc.Args) extends DokkaConfiguration:
+  override def getOutputDir: File = args.output
   override def getCacheRoot: File = null
   override def getOfflineMode: Boolean = false
   override def getFailOnWarning: Boolean = false
@@ -17,21 +17,21 @@ case class DottyDokkaConfig(docConfiguration: DocConfiguration) extends DokkaCon
   override def getModuleName(): String = "ModuleName"
   override def getModuleVersion(): String = ""
 
-  lazy val sourceLinks: SourceLinks = SourceLinks.load(docConfiguration)
+  lazy val sourceLinks: SourceLinks = SourceLinks.load(args)
 
-  lazy val staticSiteContext = docConfiguration.args.docsRoot.map(path => StaticSiteContext(
+  lazy val staticSiteContext = args.docsRoot.map(path => StaticSiteContext(
       File(path).getAbsoluteFile(),
       Set(mkSourceSet.asInstanceOf[SourceSetWrapper]),
-      docConfiguration.args,
+      args,
       sourceLinks
     ))
 
   override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] = JList()
 
   lazy val mkSourceSet: DokkaSourceSet =
     new DokkaSourceSetImpl(
-      /*displayName=*/ docConfiguration.args.name,
-      /*sourceSetID=*/ new DokkaSourceSetID(docConfiguration.args.name, "main"),
+      /*displayName=*/ args.name,
+      /*sourceSetID=*/ new DokkaSourceSetID(args.name, "main"),
       /*classpath=*/ JList(),
       /*sourceRoots=*/ JSet(),
       /*dependentSourceSets=*/ JSet(),

scala3doc/src/dotty/dokka/DottyDokkaPlugin.scala

@@ -14,7 +14,7 @@ import org.jetbrains.dokka.base.parsers._
 import org.jetbrains.dokka.plugability.DokkaContext
 import collection.JavaConverters._
 import org.jetbrains.dokka.model.properties.PropertyContainer
-import dotty.dokka.tasty.{DokkaTastyInspector, SbtDokkaTastyInspector}
+import dotty.dokka.tasty.DokkaTastyInspector
 import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.dokka.base.signatures.SignatureProvider
@@ -170,7 +170,7 @@ class DottyDokkaPlugin extends DokkaJavaPlugin:
 
 extension (ctx: DokkaContext):
   def siteContext: Option[StaticSiteContext] = ctx.getConfiguration.asInstanceOf[DottyDokkaConfig].staticSiteContext
-  def args: Args = ctx.getConfiguration.asInstanceOf[DottyDokkaConfig].docConfiguration.args
+  def args: Scala3doc.Args = ctx.getConfiguration.asInstanceOf[DottyDokkaConfig].args
 
 // TODO (https://github.com/lampepfl/scala3doc/issues/232): remove once problem is fixed in Dokka
 extension [T]  (builder: ExtensionBuilder[T]):