Merge pull request #3610 from VirtusLab/stable

Back port of documentation changes to main

Author: Gedochao

modules/directives/src/main/scala/scala/build/preprocessing/directives/Benchmarking.scala

@@ -16,6 +16,8 @@ import scala.build.{Positioned, options}
 import scala.cli.commands.SpecificationLevel
 
 @DirectiveGroupName("Benchmarking options")
+@DirectiveExamples(s"//> using jmh")
+@DirectiveExamples(s"//> using jmh true")
 @DirectiveExamples(s"//> using jmhVersion ${Constants.jmhVersion}")
 @DirectiveUsage(
   "//> using jmh _value_ | using jmhVersion _value_",

modules/directives/src/main/scala/scala/build/preprocessing/directives/ComputeVersion.scala

@@ -22,11 +22,8 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveUsage("//> using computeVersion git:tag", "`//> using computeVersion` _method_")
 @DirectiveDescription("Method used to compute the version for BuildInfo")
 @DirectiveLevel(SpecificationLevel.RESTRICTED)
-// format: off
-final case class ComputeVersion(
-    computeVersion: Option[Positioned[String]] = None
-) extends HasBuildOptions {
-  // format: on
+final case class ComputeVersion(computeVersion: Option[Positioned[String]] = None)
+    extends HasBuildOptions {
 
   def buildOptions: Either[BuildException, BuildOptions] = either {
     BuildOptions(

modules/directives/src/main/scala/scala/build/preprocessing/directives/CustomJar.scala

@@ -26,8 +26,16 @@ import scala.util.{Failure, Success, Try}
 @DirectiveUsage(
   "`//> using jar `_path_ | `//> using jars `_path1_ _path2_ …",
   """`//> using jar` _path_
-    |
     |`//> using jars` _path1_ _path2_ …
+    |
+    |`//> using test.jar` _path_
+    |`//> using test.jars` _path1_ _path2_ …
+    |
+    |`//> using source.jar` _path_
+    |`//> using source.jars` _path1_ _path2_ …
+    |
+    |`//> using test.source.jar` _path_
+    |`//> using test.source.jars` _path1_ _path2_ …
     |""".stripMargin
 )
 @DirectiveDescription("Manually add JAR(s) to the class path")

modules/directives/src/main/scala/scala/build/preprocessing/directives/Dependency.scala

@@ -19,17 +19,35 @@ import scala.build.preprocessing.directives.DirectiveUtil.*
 import scala.cli.commands.SpecificationLevel
 
 @DirectiveExamples("//> using dep com.lihaoyi::os-lib:0.9.1")
+@DirectiveExamples(
+  "//> using dep tabby:tabby:0.2.3,url=https://github.com/bjornregnell/tabby/releases/download/v0.2.3/tabby_3-0.2.3.jar"
+)
 @DirectiveExamples("//> using test.dep org.scalatest::scalatest:3.2.10")
 @DirectiveExamples("//> using test.dep org.scalameta::munit:0.7.29")
 @DirectiveExamples(
   "//> using compileOnly.dep com.github.plokhotnyuk.jsoniter-scala::jsoniter-scala-macros:2.23.2"
 )
 @DirectiveExamples(
-  "//> using dep tabby:tabby:0.2.3,url=https://github.com/bjornregnell/tabby/releases/download/v0.2.3/tabby_3-0.2.3.jar"
+  "//> using scalafix.dep com.github.xuwei-k::scalafix-rules:0.5.1"
 )
 @DirectiveUsage(
   "//> using dep org:name:ver | //> using deps org:name:ver org2:name2:ver2",
-  "`//> using dep` _org_`:`name`:`ver"
+  """`//> using dep` _org_`:`name`:`ver
+    |`//> using deps` _org_`:`name`:`ver _org_`:`name`:`ver
+    |`//> using dependencies` _org_`:`name`:`ver _org_`:`name`:`ver
+    |
+    |`//> using test.dep` _org_`:`name`:`ver
+    |`//> using test.deps` _org_`:`name`:`ver _org_`:`name`:`ver
+    |`//> using test.dependencies` _org_`:`name`:`ver _org_`:`name`:`ver
+    |
+    |`//> using compileOnly.dep` _org_`:`name`:`ver
+    |`//> using compileOnly.deps` _org_`:`name`:`ver _org_`:`name`:`ver
+    |`//> using compileOnly.dependencies` _org_`:`name`:`ver _org_`:`name`:`ver
+    |
+    |`//> using scalafix.dep` _org_`:`name`:`ver
+    |`//> using scalafix.deps` _org_`:`name`:`ver _org_`:`name`:`ver
+    |`//> using scalafix.dependencies` _org_`:`name`:`ver _org_`:`name`:`ver
+    |""".stripMargin
 )
 @DirectiveDescription("Add dependencies")
 @DirectiveLevel(SpecificationLevel.MUST)

modules/directives/src/main/scala/scala/build/preprocessing/directives/Exclude.scala

@@ -22,11 +22,7 @@ import scala.util.Try
 )
 @DirectiveDescription("Exclude sources from the project")
 @DirectiveLevel(SpecificationLevel.SHOULD)
-// format: off
-final case class Exclude(
-  exclude: List[Positioned[String]] = Nil
-) extends HasBuildOptions {
-// format: on
+final case class Exclude(exclude: List[Positioned[String]] = Nil) extends HasBuildOptions {
   def buildOptions: Either[BuildException, BuildOptions] = either {
     BuildOptions(
       internal = InternalOptions(

modules/directives/src/main/scala/scala/build/preprocessing/directives/JavaHome.scala

@@ -16,12 +16,10 @@ import scala.util.Try
 )
 @DirectiveDescription("Sets Java home used to run your application or tests")
 @DirectiveLevel(SpecificationLevel.SHOULD)
-// format: off
 final case class JavaHome(
   javaHome: DirectiveValueParser.WithScopePath[Option[Positioned[String]]] =
     DirectiveValueParser.WithScopePath.empty(None)
 ) extends HasBuildOptions {
-  // format: on
   def buildOptions: Either[BuildException, BuildOptions] = either {
     javaHome.value match {
       case None => BuildOptions()

modules/directives/src/main/scala/scala/build/preprocessing/directives/JavaOptions.scala

@@ -12,7 +12,12 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveExamples("//> using test.javaOpt -Dsomething=a")
 @DirectiveUsage(
   "//> using javaOpt _options_",
-  "`//> using javaOpt` _options_"
+  """`//> using javaOpt` _options_
+    |`//> using javaOptions` _options_`
+    |
+    |`//> using test.javaOpt` _options_
+    |`//> using test.javaOptions` _options_`
+    |""".stripMargin
 )
 @DirectiveDescription("Add Java options which will be passed when running an application.")
 @DirectiveLevel(SpecificationLevel.MUST)

modules/directives/src/main/scala/scala/build/preprocessing/directives/JavaProps.scala

@@ -14,8 +14,10 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveUsage(
   "//> using javaProp _key=val_",
   """`//> using javaProp` _key=value_
-    |
     |`//> using javaProp` _key_
+    |
+    |`//> using test.javaProp` _key=value_
+    |`//> using test.javaProp` _key_
     |""".stripMargin
 )
 @DirectiveDescription("Add Java properties")

modules/directives/src/main/scala/scala/build/preprocessing/directives/JavacOptions.scala

@@ -12,7 +12,12 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveExamples("//> using test.javacOpt -source 1.8 -target 1.8")
 @DirectiveUsage(
   "//> using javacOpt _options_",
-  "`//> using javacOpt` _options_"
+  """`//> using javacOpt` _options_
+    |`//> using javacOptions` _options_
+    |
+    |`//> using test.javacOpt` _options_
+    |`//> using test.javacOptions` _options_
+    |""".stripMargin
 )
 @DirectiveDescription("Add Javac options which will be passed when compiling sources.")
 @DirectiveLevel(SpecificationLevel.SHOULD)

modules/directives/src/main/scala/scala/build/preprocessing/directives/Jvm.scala

@@ -19,11 +19,7 @@ import scala.cli.commands.SpecificationLevel
     "scala-cli uses [coursier](https://get-coursier.io/) to fetch JVMs, so you can use `cs java --available` to list the available JVMs."
 )
 @DirectiveLevel(SpecificationLevel.SHOULD)
-// format: off
-final case class Jvm(
-  jvm: Option[Positioned[String]] = None
-) extends HasBuildOptions {
-  // format: on
+final case class Jvm(jvm: Option[Positioned[String]] = None) extends HasBuildOptions {
   def buildOptions: Either[BuildException, BuildOptions] = {
     val buildOpt = BuildOptions(
       javaOptions = options.JavaOptions(