Add scaladoc to BuildInfo, make docs auto-generated

MaciejG604 · MaciejG604 · commit a9507897aca5 · 2023-08-07T13:58:57.000+02:00
diff --git a/modules/build/src/test/scala/scala/build/tests/SourceGeneratorTests.scala b/modules/build/src/test/scala/scala/build/tests/SourceGeneratorTests.scala
@@ -39,7 +39,7 @@ class SourceGeneratorTests extends munit.FunSuite {
     )
   )
 
-  private def normalizeResolvers(contents: String): String =
+  private def normalizeContents(contents: String): String =
     contents
       .replaceAll(
         "ivy:file:[^\"]*scala-cli-tests-extra-repo[^\"]*/local-repo[^\"]*",
@@ -48,7 +48,9 @@ class SourceGeneratorTests extends munit.FunSuite {
       .replaceAll(
         "ivy:file:[^\"]*\\.ivy2/local[^\"]*",
         "ivy:file:.../.ivy2/local/"
-      )
+      ).linesWithSeparators
+      .filterNot(_.stripLeading().startsWith("/**"))
+      .mkString
 
   test(s"BuildInfo source generated") {
     val inputs = TestInputs(
@@ -85,7 +87,8 @@ class SourceGeneratorTests extends munit.FunSuite {
 
         val buildInfoContent = os.read(buildInfoPath)
 
-        expect(normalizeResolvers(buildInfoContent) ==
+        assertNoDiff(
+          normalizeContents(buildInfoContent),
           s"""package scala.cli.build
              |
              |object BuildInfo {
@@ -97,7 +100,6 @@ class SourceGeneratorTests extends munit.FunSuite {
              |  val scalaNativeVersion = None
              |  val mainClass = Some("Main")
              |
-             |
              |  object Main {
              |    val sources = Seq("${root / "main.scala"}")
              |    val scalacOptions = Seq("-Xasync")
@@ -117,9 +119,9 @@ class SourceGeneratorTests extends munit.FunSuite {
              |    val resourceDirs = Nil
              |    val customJarsDecls = Nil
              |  }
-             |
              |}
-             |""".stripMargin)
+             |""".stripMargin
+        )
     }
   }
 
@@ -160,7 +162,8 @@ class SourceGeneratorTests extends munit.FunSuite {
 
         val buildInfoContent = os.read(buildInfoPath)
 
-        expect(normalizeResolvers(buildInfoContent) ==
+        assertNoDiff(
+          normalizeContents(buildInfoContent),
           s"""package scala.cli.build
              |
              |object BuildInfo {
@@ -172,7 +175,6 @@ class SourceGeneratorTests extends munit.FunSuite {
              |  val scalaNativeVersion = Some("0.4.6")
              |  val mainClass = Some("Main")
              |
-             |
              |  object Main {
              |    val sources = Seq("${root / "main.scala"}")
              |    val scalacOptions = Seq("-Xasync")
@@ -192,9 +194,9 @@ class SourceGeneratorTests extends munit.FunSuite {
              |    val resourceDirs = Nil
              |    val customJarsDecls = Nil
              |  }
-             |
              |}
-             |""".stripMargin)
+             |""".stripMargin
+        )
     }
   }
 
@@ -236,7 +238,8 @@ class SourceGeneratorTests extends munit.FunSuite {
 
         val buildInfoContent = os.read(buildInfoPath)
 
-        expect(normalizeResolvers(buildInfoContent) ==
+        assertNoDiff(
+          normalizeContents(buildInfoContent),
           s"""package scala.cli.build
              |
              |object BuildInfo {
@@ -248,7 +251,6 @@ class SourceGeneratorTests extends munit.FunSuite {
              |  val scalaNativeVersion = None
              |  val mainClass = Some("Main")
              |
-             |
              |  object Main {
              |    val sources = Seq("${root / "main.scala"}")
              |    val scalacOptions = Seq("-Xasync")
@@ -268,9 +270,9 @@ class SourceGeneratorTests extends munit.FunSuite {
              |    val resourceDirs = Nil
              |    val customJarsDecls = Nil
              |  }
-             |
              |}
-             |""".stripMargin)
+             |""".stripMargin
+        )
     }
   }
 
@@ -309,7 +311,8 @@ class SourceGeneratorTests extends munit.FunSuite {
 
         val buildInfoContent = os.read(buildInfoPath)
 
-        expect(normalizeResolvers(buildInfoContent) ==
+        assertNoDiff(
+          normalizeContents(buildInfoContent),
           s"""package scala.cli.build
              |
              |object BuildInfo {
@@ -321,7 +324,6 @@ class SourceGeneratorTests extends munit.FunSuite {
              |  val scalaNativeVersion = None
              |  val mainClass = Some("Main")
              |
-             |
              |  object Main {
              |    val sources = Seq("${root / "main.scala"}")
              |    val scalacOptions = Seq("-Xasync")
@@ -341,9 +343,9 @@ class SourceGeneratorTests extends munit.FunSuite {
              |    val resourceDirs = Nil
              |    val customJarsDecls = Nil
              |  }
-             |
              |}
-             |""".stripMargin)
+             |""".stripMargin
+        )
     }
   }
 }
diff --git a/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala b/modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala
@@ -11,6 +11,7 @@ import shapeless.tag
 import java.nio.charset.StandardCharsets
 import java.util
 
+import scala.build.info.{ArtifactId, BuildInfo, ExportDependencyFormat, ScopedBuildInfo}
 import scala.build.options.{BuildOptions, BuildRequirements, WithBuildRequirements}
 import scala.build.preprocessing.directives.DirectiveHandler
 import scala.build.preprocessing.directives.DirectivesPreprocessingUtils.*
@@ -481,6 +482,93 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
     b.toString
   }
 
+  private def buildInfoContent: String = {
+    val b = new StringBuilder
+
+    b.section(
+      """---
+        |title: BuildInfo
+        |sidebar_position: 6
+        |---""".stripMargin
+    )
+    b.section(
+      """:::caution
+        |BuildInfo is a restricted feature and requires setting the `--power` option to be used.
+        |You can pass it explicitly or set it globally by running:
+        |
+        |    scala-cli config power true
+        |:::""".stripMargin
+    )
+
+    b.section(
+      """During the building process Scala CLI collects information about the project's configuration,
+        |both from the console options and `using directives` found in the project's sources.
+        |You can access this information from your code using the `BuildInfo` object, that's automatically generated for your
+        |build on compile when that information changes.""".stripMargin
+    )
+
+    b.section(
+      """To enable BuildInfo generation pass the `--build-info` option to Scala CLI or use a
+        |`//> using buildInfo` directive.""".stripMargin
+    )
+
+    b.section(
+      """## Usage
+        |
+        |The generated BuildInfo object is available on the project's classpath. To access it you need to import it first.
+        |It is available in the package `scala.cli.build` so use
+        |```scala
+        |import scala.cli.build.BuildInfo
+        |```
+        |to import it.
+        |
+        |Below you can find an example instance of the BuildInfo object, with all fields explained.
+        |Some of the values have been shortened for readability.""".stripMargin
+    )
+
+    val osLibDep = ExportDependencyFormat("com.lihaoyi", ArtifactId("os-lib", "os-lib_3"), "0.9.1")
+    val toolkitDep =
+      ExportDependencyFormat("org.scala-lang", ArtifactId("toolkit", "toolkit_3"), "latest.release")
+
+    val mainScopedBuildInfo = ScopedBuildInfo(BuildOptions(), Seq(".../Main.scala")).copy(
+      scalacOptions = Seq("-Werror"),
+      scalaCompilerPlugins = Nil,
+      dependencies = Seq(osLibDep),
+      resolvers = Seq("https://repo1.maven.org/maven2", "ivy:file:..."),
+      resourceDirs = Seq(".../resources"),
+      customJarsDecls = Seq(".../AwesomeJar1.jar", ".../AwesomeJar2.jar")
+    )
+
+    val testScopedBuildInfo = ScopedBuildInfo(BuildOptions(), Seq(".../MyTests.scala")).copy(
+      scalacOptions = Seq("-Vdebug"),
+      scalaCompilerPlugins = Nil,
+      dependencies = Seq(toolkitDep),
+      resolvers = Seq("https://repo1.maven.org/maven2", "ivy:file:..."),
+      resourceDirs = Seq(".../test/resources"),
+      customJarsDecls = Nil
+    )
+
+    val buildInfo = BuildInfo(BuildOptions()).copy(
+      scalaVersion = Some("3.3.0"),
+      platform = Some("JVM"),
+      jvmVersion = Some("11"),
+      scalaJsVersion = None,
+      jsEsVersion = None,
+      scalaNativeVersion = None,
+      mainClass = Some("Main")
+    )
+      .withScope("main", mainScopedBuildInfo)
+      .withScope("test", testScopedBuildInfo)
+
+    b.section(
+      s"""```scala
+         |${buildInfo.generateContents().strip()}
+         |```""".stripMargin
+    )
+
+    b.mkString
+  }
+
   def run(options: InternalDocOptions, args: RemainingArgs): Unit = {
 
     val scalaCli = new ScalaCliCommands(
@@ -512,6 +600,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
       requireDirectiveHandlers,
       onlyRestricted = false
     )
+
     val restrictedDirectivesContent = usingContent(
       allUsingDirectiveHandlers.filterNot(_.isRestricted),
       requireDirectiveHandlers.filterNot(_.isRestricted),
@@ -524,6 +613,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
         (os.rel / "cli-options.md")                           -> allCliOptionsContent,
         (os.rel / "commands.md")                              -> allCommandsContent,
         (os.rel / "directives.md")                            -> allDirectivesContent,
+        (os.rel / "build-info.md")                            -> buildInfoContent,
         (os.rel / restrictedDocsDir / "cli-options.md")       -> restrictedCliOptionsContent,
         (os.rel / restrictedDocsDir / "commands.md")          -> restrictedCommandsContent,
         (os.rel / restrictedDocsDir / "directives.md")        -> restrictedDirectivesContent,
@@ -551,6 +641,7 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
       maybeWrite(options.outputPath / "cli-options.md", allCliOptionsContent)
       maybeWrite(options.outputPath / "commands.md", allCommandsContent)
       maybeWrite(options.outputPath / "directives.md", allDirectivesContent)
+      maybeWrite(options.outputPath / "build-info.md", buildInfoContent)
 
       maybeWrite(
         options.outputPath / restrictedDocsDir / "cli-options.md",
diff --git a/modules/options/src/main/scala/scala/build/info/BuildInfo.scala b/modules/options/src/main/scala/scala/build/info/BuildInfo.scala
@@ -31,18 +31,38 @@ final case class BuildInfo(
     val nl     = System.lineSeparator()
     val indent = " " * 2
     val stringVals = Seq(
+      "/** version of Scala used to compile this project */",
       s"val scalaVersion = \"${escapeBackslashes(scalaVersion.getOrElse(Constants.defaultScalaVersion))}\"",
+      "/** target platform of this project, it can be \"JVM\" or \"JS\" or \"Native\" */",
       s"val platform = \"${escapeBackslashes(platform.getOrElse(Platform.JVM.repr))}\""
     )
 
     val optionVals = Seq(
-      "val jvmVersion ="         -> jvmVersion,
-      "val scalaJsVersion ="     -> scalaJsVersion,
-      "val jsEsVersion ="        -> jsEsVersion,
-      "val scalaNativeVersion =" -> scalaNativeVersion,
-      "val mainClass ="          -> mainClass
-    ).map { case (prefix, opt) =>
-      opt.map(v => s"$prefix Some(\"${escapeBackslashes(v)}\")").getOrElse(s"$prefix None")
+      Seq(
+        "/** version of JVM, if it's the target platform */",
+        "val jvmVersion ="
+      ) -> jvmVersion,
+      Seq(
+        "/** version of Scala.js, if it's the target platform */",
+        "val scalaJsVersion ="
+      ) -> scalaJsVersion,
+      Seq(
+        "/** Scala.js ECMA Script version, if Scala.js is the target platform */",
+        "val jsEsVersion ="
+      ) -> jsEsVersion,
+      Seq(
+        "/** version of Scala Native, if it's the target platform */",
+        "val scalaNativeVersion ="
+      ) -> scalaNativeVersion,
+      Seq(
+        "/** Main class specified for the project */",
+        "val mainClass ="
+      ) -> mainClass
+    ).flatMap { case (Seq(scaladoc, prefix), opt) =>
+      Seq(
+        scaladoc,
+        opt.map(v => s"$prefix Some(\"${escapeBackslashes(v)}\")").getOrElse(s"$prefix None")
+      )
     }
 
     val allVals = stringVals ++ optionVals
@@ -52,17 +72,18 @@ final case class BuildInfo(
         yield {
           val scopedBuildInfoVals = scopedBuildInfo.generateContentLines()
             .mkString(indent, nl + indent * 2, "")
-          s"""${indent}object ${scopeName.capitalize} {
+          s"""$indent/** Information about the ${scopeName.capitalize} scope */
+             |${indent}object ${scopeName.capitalize} {
              |$indent$scopedBuildInfoVals
-             |$indent}
-             |""".stripMargin
+             |$indent}""".stripMargin
         }
 
     s"""package scala.cli.build
        |
+       |/** Information about the build gathered by Scala CLI */
        |object BuildInfo {
        |${allVals.mkString(indent, nl + indent, nl)}
-       |${scopesContents.mkString(nl, nl, "")}
+       |${scopesContents.mkString(nl * 2)}
        |}
        |""".stripMargin
   }
diff --git a/modules/options/src/main/scala/scala/build/info/ScopedBuildInfo.scala b/modules/options/src/main/scala/scala/build/info/ScopedBuildInfo.scala
@@ -25,22 +25,27 @@ final case class ScopedBuildInfo(
 
   def generateContentLines(): Seq[String] =
     Seq(
-      s"val sources = "              -> sources,
-      s"val scalacOptions = "        -> scalacOptions,
-      s"val scalaCompilerPlugins = " -> scalaCompilerPlugins.map(_.toString()),
-      s"val dependencies = "         -> dependencies.map(_.toString()),
-      s"val resolvers = "            -> resolvers,
-      s"val resourceDirs = "         -> resourceDirs,
-      s"val customJarsDecls = "      -> customJarsDecls
-    ).map { case (prefix, values) =>
+      Seq("/** sources found for the scope */", "val sources = ")        -> sources,
+      Seq("/** scalac options for the scope */", "val scalacOptions = ") -> scalacOptions,
+      Seq(
+        "/** compiler plugins used in this scope */",
+        "val scalaCompilerPlugins = "
+      ) -> scalaCompilerPlugins.map(_.toString()),
+      Seq("/** dependencies used in this scope */", "val dependencies = ") -> dependencies.map(
+        _.toString()
+      ),
+      Seq("/** dependency resolvers used in this scope */", "val resolvers = ")    -> resolvers,
+      Seq("/** resource directories used in this scope */", "val resourceDirs = ") -> resourceDirs,
+      Seq("/** custom jars added to this scope */", "val customJarsDecls = ") -> customJarsDecls
+    ).flatMap { case (Seq(scaladoc, prefix), values) =>
       val sb = new StringBuilder
       sb.append(prefix)
       if (values.isEmpty) sb.append("Nil")
       else sb.append {
         values.map(str => s"\"${BuildInfo.escapeBackslashes(str)}\"")
           .mkString("Seq(", ", ", ")")
       }
-      sb.toString()
+      Seq(scaladoc, sb.toString())
     }
 }
 
diff --git a/website/docs/reference/bloop.md b/website/docs/reference/bloop.md
@@ -1,6 +1,6 @@
 ---
 title: Interaction with Bloop server
-sidebar_position: 6
+sidebar_position: 10
 ---
 
 # Interaction with Bloop server
diff --git a/website/docs/reference/build-info.md b/website/docs/reference/build-info.md
