Restrict cmd options and clean up messages

- remove duplicated --cross option
- gh-token share same message
- add dome desctiptions

Author: romanowski

modules/cli-options/src/main/scala/scala/cli/commands/AboutOptions.scala

@@ -11,6 +11,7 @@ final case class AboutOptions(
   @Recurse
     verbosity: VerbosityOptions = VerbosityOptions(),
   @Hidden
+  @HelpMessage(HelpMessages.passwordOption)
     ghToken: Option[PasswordOption] = None
 )
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/BenchmarkingOptions.scala

@@ -5,10 +5,10 @@ import caseapp._
 // format: off
 final case class BenchmarkingOptions(
   @Group("Benchmarking")
-  @HelpMessage("Run JMH benchmarks")
+  @HelpMessage("[experimental] Run JMH benchmarks")
     jmh: Option[Boolean] = None,
   @Group("Benchmarking")
-  @HelpMessage("Set JMH version")
+  @HelpMessage("[experimental] Set JMH version")
   @ValueDescription("version")
     jmhVersion: Option[String] = None
 )

modules/cli-options/src/main/scala/scala/cli/commands/CompileCrossOptions.scala

@@ -4,6 +4,7 @@ import caseapp._
 
 // format: off
 final case class CrossOptions(
+    @HelpMessage("[experimental] Run given command against all provided Scala versions and/or platforms")
     cross: Option[Boolean] = None
 )
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/CrossOptions.scala

@@ -9,7 +9,7 @@ final case class DependencyUpdateOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
   @Group("DependencyUpdate")
-  @HelpMessage("Update all dependency")
+  @HelpMessage("Update all dependencies if newer version was released")
     all: Boolean = false,
 )
   // format: on

modules/cli-options/src/main/scala/scala/cli/commands/DependencyUpdateOptions.scala

@@ -4,7 +4,7 @@ import caseapp._
 import caseapp.core.help.Help
 
 // format: off
-@HelpMessage("Generate Scaladoc documentation")
+@HelpMessage("Generate Scaladoc documentation", "By default, Scala CLI sets common scaladoc options and this mechanism can be disabled by using `--default-scaladoc-opts:false`.")
 final case class DocOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
@@ -17,7 +17,7 @@ final case class DocOptions(
   @Name("f")
     force: Boolean = false,
   @Group("Doc")
-  @HelpMessage("Use default scaladoc options")
+  @HelpMessage("Control if scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.")
   @ExtraName("defaultScaladocOpts")
     defaultScaladocOptions: Option[Boolean] = None,
 )

modules/cli-options/src/main/scala/scala/cli/commands/DocOptions.scala

@@ -11,6 +11,7 @@ final case class DoctorOptions(
   @Recurse
     verbosity: VerbosityOptions = VerbosityOptions(),
   @Hidden
+  @HelpMessage(HelpMessages.passwordOption)
     ghToken: Option[PasswordOption] = None
 )
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/DoctorOptions.scala

@@ -13,7 +13,7 @@ final case class FmtOptions(
     check: Boolean = false,
 
   @Group("Format")
-  @HelpMessage("Use project filters defined in the configuration (turned on by default)")
+  @HelpMessage("Use project filters defined in the configuration. Turned on by default, use `--respect-project-filters:false` to disable it.")
     respectProjectFilters: Boolean = true,
 
   @Group("Format")
@@ -43,6 +43,7 @@ final case class FmtOptions(
 
   @Group("Format")
   @Name("F")
+  @HelpMessage("Pass argument to scalafmt.")
     scalafmtArg: List[String] = Nil,
 
   @Group("Format")
@@ -55,7 +56,7 @@ final case class FmtOptions(
   @Name("scalafmtConfSnippet")
     scalafmtConfStr: Option[String] = None,
   @Group("Format")
-  @HelpMessage("Pass a global dialect for scalafmt. This overrides whatever value is configured in the .scalafmt.conf file.")
+  @HelpMessage("Pass a global dialect for scalafmt. This overrides whatever value is configured in the .scalafmt.conf file or inferred based on Scala version used.")
   @Name("dialect")
     scalafmtDialect: Option[String] = None,
   @Group("Format")

modules/cli-options/src/main/scala/scala/cli/commands/FmtOptions.scala

@@ -0,0 +1,5 @@
+package scala.cli.commands
+
+object HelpMessages {
+  val passwordOption = "A github token used to access GitHub. Not needed in most cases."
+}

modules/cli-options/src/main/scala/scala/cli/commands/HelpMessages.scala

@@ -13,7 +13,7 @@ final case class PackageOptions(
   @Recurse
     java: SharedJavaOptions = SharedJavaOptions(),
   @Recurse
-    compileCross: CompileCrossOptions = CompileCrossOptions(),
+    compileCross: CrossOptions = CrossOptions(),
   @Recurse
     mainClass: MainClassOptions = MainClassOptions(),