Back port of documentation changes to main

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(

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

@@ -14,17 +14,9 @@ import scala.cli.commands.SpecificationLevel
 )
 @DirectiveDescription("Specify default main class")
 @DirectiveLevel(SpecificationLevel.MUST)
-// format: off
-final case class MainClass(
-  mainClass: Option[String] = None
-) extends HasBuildOptions {
-  // format: on
-  def buildOptions: Either[BuildException, BuildOptions] = {
-    val buildOpt = BuildOptions(
-      mainClass = mainClass
-    )
-    Right(buildOpt)
-  }
+final case class MainClass(mainClass: Option[String] = None) extends HasBuildOptions {
+  def buildOptions: Either[BuildException, BuildOptions] =
+    Right(BuildOptions(mainClass = mainClass))
 }
 
 object MainClass {

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

@@ -21,8 +21,13 @@ import scala.cli.commands.SpecificationLevel
 @DirectiveExamples("//> using packaging.packageType assembly")
 @DirectiveExamples("//> using packaging.output foo")
 @DirectiveExamples("//> using packaging.provided org.apache.spark::spark-sql")
-@DirectiveExamples("//> using packaging.dockerFrom openjdk:11")
 @DirectiveExamples("//> using packaging.graalvmArgs --no-fallback")
+@DirectiveExamples("//> using packaging.dockerFrom openjdk:11")
+@DirectiveExamples("//> using packaging.dockerImageTag 1.0.0")
+@DirectiveExamples("//> using packaging.dockerImageRegistry virtuslab")
+@DirectiveExamples("//> using packaging.dockerImageRepository scala-cli")
+@DirectiveExamples("//> using packaging.dockerCmd sh")
+@DirectiveExamples("//> using packaging.dockerCmd node")
 @DirectiveUsage(
   """using packaging.packageType [package type]
     |using packaging.output [destination path]
@@ -32,16 +37,30 @@ import scala.cli.commands.SpecificationLevel
     |using packaging.dockerImageTag [image tag]
     |using packaging.dockerImageRegistry [image registry]
     |using packaging.dockerImageRepository [image repository]
+    |using packaging.dockerCmd [docker command]
     |""".stripMargin,
   """`//> using packaging.packageType` _package-type_
     |
     |`//> using packaging.output` _destination-path_
     |
+    |`//> using packaging.provided` _module_
+    |
+    |`//> using packaging.graalvmArgs` _args_
+    |
+    |`//> using packaging.dockerFrom` _base-docker-image_
+    |
+    |`//> using packaging.dockerImageTag` _image-tag_
+    |
+    |`//> using packaging.dockerImageRegistry` _image-registry_
+    |
+    |`//> using packaging.dockerImageRepository` _image-repository_
+    |
+    |`//> using packaging.dockerCmd` _docker-command_
+    |
     |""".stripMargin
 )
 @DirectiveDescription("Set parameters for packaging")
 @DirectiveLevel(SpecificationLevel.RESTRICTED)
-// format: off
 final case class Packaging(
   packageType: Option[Positioned[String]] = None,
   output: Option[String] = None,
@@ -53,7 +72,6 @@ final case class Packaging(
   dockerImageRepository: Option[String] = None,
   dockerCmd: Option[String] = None
 ) extends HasBuildOptions {
-  // format: on
   def buildOptions: Either[BuildException, BuildOptions] = either {
     val maybePackageTypeOpt = packageType
       .map { input =>

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

@@ -21,19 +21,19 @@ import scala.cli.commands.SpecificationLevel
 
 @DirectiveGroupName("Platform")
 @DirectiveExamples("//> using platform scala-js")
-@DirectiveExamples("//> using platform jvm scala-native")
+@DirectiveExamples("//> using platforms jvm scala-native")
 @DirectiveUsage(
   "//> using platform (jvm|scala-js|js|scala-native|native)+",
-  "`//> using platform` (`jvm`|`scala-js`|`js`|`scala-native`|`native`)+"
+  """`//> using platform` (`jvm`|`scala-js`|`js`|`scala-native`|`native`)+
+    |`//> using platforms` (`jvm`|`scala-js`|`js`|`scala-native`|`native`)+
+    |""".stripMargin
 )
 @DirectiveDescription("Set the default platform to Scala.js or Scala Native")
 @DirectiveLevel(SpecificationLevel.SHOULD)
-// format: off
 final case class Platform(
   @DirectiveName("platform")
-    platforms: List[Positioned[String]] = Nil
+  platforms: List[Positioned[String]] = Nil
 ) extends HasBuildOptions {
-  // format: on
 
   private def split(input: String): (String, Option[String]) = {
     val idx = input.indexOf(':')

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

@@ -13,20 +13,52 @@ import scala.cli.commands.SpecificationLevel
 @DirectivePrefix("publish.")
 @DirectiveExamples("//> using publish.organization io.github.myself")
 @DirectiveExamples("//> using publish.name my-library")
+@DirectiveExamples("//> using publish.moduleName scala-cli_3")
 @DirectiveExamples("//> using publish.version 0.1.1")
+@DirectiveExamples("//> using publish.url https://github.com/VirtusLab/scala-cli")
+@DirectiveExamples("//> using publish.license MIT")
+@DirectiveExamples("//> using publish.vcs https://github.com/VirtusLab/scala-cli.git")
+@DirectiveExamples("//> using publish.vcs github:VirtusLab/scala-cli")
+@DirectiveExamples("//> using publish.description \"Lorem ipsum dolor sit amet\"")
+@DirectiveExamples("//> using publish.developer alexme|Alex Me|https://alex.me")
+@DirectiveExamples(
+  "//> using publish.developers alexme|Alex Me|https://alex.me Gedochao|Gedo Chao|https://github.com/Gedochao"
+)
+@DirectiveExamples("//> using publish.scalaVersionSuffix _2.13")
+@DirectiveExamples("//> using publish.scalaVersionSuffix _3")
+@DirectiveExamples("//> using publish.scalaPlatformSuffix _sjs1")
+@DirectiveExamples("//> using publish.scalaPlatformSuffix _native0.4")
 @DirectiveUsage(
-  "//> using publish.(organization|name|version) [value]",
+  "//> using publish.[key] [value]",
   """`//> using publish.organization` value
     |
     |`//> using publish.name` value
     |
+    |`//> using publish.moduleName` value
+    |
     |`//> using publish.version` value
     |
+    |`//> using publish.url` value
+    |
+    |`//> using publish.license` value
+    |
+    |`//> using publish.vcs` value
+    |`//> using publish.scm` value
+    |`//> using publish.versionControl` value
+    |
+    |`//> using publish.description` value
+    |
+    |`//> using publish.developer` value
+    |`//> using publish.developers` value1 value2
+    |
+    |`//> using publish.scalaVersionSuffix` value
+    |
+    |`//> using publish.scalaPlatformSuffix` value
+    |
     |""".stripMargin
 )
 @DirectiveDescription("Set parameters for publishing")
 @DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
-// format: off
 final case class Publish(
   organization: Option[Positioned[String]] = None,
   name: Option[Positioned[String]] = None,
@@ -36,14 +68,13 @@ final case class Publish(
   license: Option[Positioned[String]] = None,
   @DirectiveName("scm")
   @DirectiveName("versionControl")
-    vcs: Option[Positioned[String]] = None,
+  vcs: Option[Positioned[String]] = None,
   description: Option[String] = None,
   @DirectiveName("developer")
-    developers: List[Positioned[String]] = Nil,
+  developers: List[Positioned[String]] = Nil,
   scalaVersionSuffix: Option[String] = None,
   scalaPlatformSuffix: Option[String] = None
 ) extends HasBuildOptions {
-  // format: on
   def buildOptions: Either[BuildException, BuildOptions] = either {
 
     val maybeLicense = license

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

@@ -19,12 +19,10 @@ import scala.cli.commands.SpecificationLevel
 )
 @DirectiveDescription(Repository.usageMsg)
 @DirectiveLevel(SpecificationLevel.SHOULD)
-// format: off
 final case class Repository(
   @DirectiveName("repository")
-    repositories: List[String] = Nil
+  repositories: List[String] = Nil
 ) extends HasBuildOptions {
-  // format: on
   def buildOptions: Either[BuildException, BuildOptions] = {
     val buildOpt = BuildOptions(
       classPathOptions = ClassPathOptions(

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

@@ -18,12 +18,10 @@ import scala.cli.commands.SpecificationLevel
   "`//> using target.platform` _platform_"
 )
 @DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
-// format: off
 final case class RequirePlatform(
   @DirectiveName("platform")
-    platforms: List[Positioned[String]] = Nil
+  platforms: List[Positioned[String]] = Nil
 ) extends HasBuildRequirements {
-  // format: on
   def buildRequirements: Either[BuildException, BuildRequirements] = either {
     val platformSet = value {
       Platform.parseSpec(platforms.map(_.value).map(options.Platform.normalize)).toRight {

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

@@ -15,8 +15,12 @@ import scala.cli.commands.SpecificationLevel
     |
     |//> using resourceDirs _path1_ _path2_ …""".stripMargin,
   """`//> using resourceDir` _path_
+    |`//> using resourceDirs` _path1_ _path2_ …
     |
-    |`//> using resourceDirs` _path1_ _path2_ …""".stripMargin
+    |`//> using test.resourceDir` _path_
+    |`//> using test.resourceDirs` _path1_ _path2_ …
+    |
+    |""".stripMargin
 )
 @DirectiveDescription("Manually add a resource directory to the class path")
 @DirectiveLevel(SpecificationLevel.SHOULD)