Add more detail for sub-commands' help messages

modules/cli/src/main/scala/scala/cli/commands/addpath/AddPathOptions.scala

@@ -3,12 +3,15 @@ package scala.cli.commands.addpath
 import caseapp.*
 
 import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions}
+import scala.cli.commands.tags
 
 // format: off
+@HelpMessage("Add entries to the PATH environment variable.")
 final case class AddPathOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
-  title: String = ""
+  @Tag(tags.restricted)
+    title: String = ""
 ) extends HasLoggingOptions
 // format: on
 

modules/cli/src/main/scala/scala/cli/commands/bloop/BloopExitOptions.scala

@@ -2,10 +2,14 @@ package scala.cli.commands.bloop
 
 import caseapp.*
 
-import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions}
+import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions}
 
 
 // format: off
+@HelpMessage(
+  s"""Stop Bloop if an instance is running.
+     |
+     |${HelpMessages.bloopInfo}""".stripMargin)
 final case class BloopExitOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),

modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala

@@ -2,9 +2,17 @@ package scala.cli.commands.bloop
 
 import caseapp.*
 
-import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions}
+import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions}
+import scala.cli.commands.tags
 
 // format: off
+@HelpMessage(
+  s"""Interact with Bloop (the build server) or check its status.
+     |
+     |This sub-command allows to check the current status of Bloop.
+     |If Bloop isn't currently running, it will be started.
+     |
+     |${HelpMessages.bloopInfo}""".stripMargin)
 final case class BloopOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -17,6 +25,7 @@ final case class BloopOptions(
 
   @ExtraName("workingDir")
   @ExtraName("dir")
+  @Tag(tags.restricted)
     workingDirectory: Option[String] = None
 ) extends HasLoggingOptions {
   // format: on

modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOutputOptions.scala

@@ -2,9 +2,13 @@ package scala.cli.commands.bloop
 
 import caseapp.*
 
-import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions}
+import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions}
 
 // format: off
+@HelpMessage(
+  s"""Print Bloop output.
+     |
+     |${HelpMessages.bloopInfo}""".stripMargin)
 final case class BloopOutputOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),

modules/cli/src/main/scala/scala/cli/commands/bloop/BloopStartOptions.scala

@@ -2,9 +2,14 @@ package scala.cli.commands.bloop
 
 import caseapp.*
 
-import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions}
+import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions}
+import scala.cli.commands.tags
 
 // format: off
+@HelpMessage(
+  s"""Starts a Bloop instance, if none is running.
+     |
+     |${HelpMessages.bloopInfo}""".stripMargin)
 final case class BloopStartOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -15,6 +20,7 @@ final case class BloopStartOptions(
   @Recurse
     coursier: CoursierOptions = CoursierOptions(),
   @Name("f")
+  @Tag(tags.restricted)
     force: Boolean = false
 ) extends HasLoggingOptions
 // format: on

modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala

@@ -2,10 +2,21 @@ package scala.cli.commands.bsp
 
 import caseapp.*
 
-import scala.cli.commands.shared.{HasSharedOptions, SharedOptions}
+import scala.cli.ScalaCli.fullRunnerName
+import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
+import scala.cli.commands.tags
 
 // format: off
-@HelpMessage("Start BSP server")
+@HelpMessage(
+  s"""Start BSP server.
+     |
+     |BSP stands for Build Server Protocol.
+     |For more information refer to https://build-server-protocol.github.io/
+     |
+     |This sub-command is not designed to be used by a human.
+     |It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported.
+     |
+     |${HelpMessages.docsWebsiteReference}""".stripMargin)
 final case class BspOptions(
   // FIXME There might be too many options in SharedOptions for the bsp command…
   @Recurse
@@ -14,7 +25,8 @@ final case class BspOptions(
   @HelpMessage("Command-line options JSON file")
   @ValueDescription("path")
   @Hidden
-  jsonOptions: Option[String] = None
+  @Tag(tags.implementation)
+    jsonOptions: Option[String] = None
 ) extends HasSharedOptions {
   // format: on
 }

modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala

@@ -2,15 +2,22 @@ package scala.cli.commands.clean
 
 import caseapp.*
 
+import scala.cli.ScalaCli.fullRunnerName
 import scala.cli.commands.shared.{
   HasLoggingOptions,
+  HelpMessages,
   LoggingOptions,
   SharedBspFileOptions,
   SharedWorkspaceOptions
 }
 
 // format: off
-@HelpMessage("Clean the workspace")
+@HelpMessage(
+  s"""Clean the workspace.
+    |
+    |Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned.
+    |
+    |${HelpMessages.commandDocWebsiteReference("clean")}""".stripMargin)
 final case class CleanOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),

modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala

@@ -3,11 +3,26 @@ package scala.cli.commands.compile
 import caseapp.*
 import caseapp.core.help.Help
 
-import scala.cli.commands.shared.{CrossOptions, HasSharedOptions, SharedOptions, SharedWatchOptions}
+import scala.cli.commands.shared.{
+  CrossOptions,
+  HasSharedOptions,
+  HelpMessages,
+  SharedOptions,
+  SharedWatchOptions
+}
 import scala.cli.commands.tags
 
+@HelpMessage({
+  val cmdName = "compile"
+  s"""Compile Scala code.
+     |
+     |${HelpMessages.commandConfigurations(cmdName)}
+     |
+     |${HelpMessages.acceptedInputs}
+     |
+     |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
+})
 // format: off
-@HelpMessage("Compile Scala code")
 final case class CompileOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),

modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala

@@ -2,16 +2,27 @@ package scala.cli.commands.config
 
 import caseapp.*
 
+import scala.cli.ScalaCli.{fullRunnerName, progName}
 import scala.cli.commands.pgp.PgpScalaSigningOptions
 import scala.cli.commands.shared.{
   CoursierOptions,
   HasLoggingOptions,
+  HelpMessages,
   LoggingOptions,
   SharedJvmOptions
 }
 import scala.cli.commands.tags
 
 // format: off
+@HelpMessage(
+  s"""Configure global settings for $fullRunnerName.
+     |
+     |Syntax:
+     |  $progName ${HelpMessages.PowerString}config key value
+     |For example, to globally set the interactive mode:
+     |  $progName ${HelpMessages.PowerString}config interactive true
+     |
+     |${HelpMessages.commandDocWebsiteReference("misc/config")}""".stripMargin)
 final case class ConfigOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -25,10 +36,10 @@ final case class ConfigOptions(
   @Group("Config")
   @HelpMessage("Dump config DB as JSON")
   @Hidden
+  @Tag(tags.implementation)
     dump: Boolean = false,
   @Group("Config")
   @HelpMessage("Create PGP key in config")
-  @Tag(tags.restricted)
     createPgpKey: Boolean = false,
   @Group("Config")
   @HelpMessage("Email to use to create PGP key in config")
@@ -45,6 +56,7 @@ final case class ConfigOptions(
   @Group("Config")
   @HelpMessage("Remove an entry from config")
   @ExtraName("remove")
+  @Tag(tags.restricted)
     unset: Boolean = false,
   @Group("Config")
   @HelpMessage("For repository.credentials and publish.credentials, whether these credentials should be HTTPS only (default: true)")

modules/cli/src/main/scala/scala/cli/commands/default/DefaultFileOptions.scala

@@ -2,24 +2,34 @@ package scala.cli.commands.default
 
 import caseapp.*
 
-import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions}
+import scala.cli.ScalaCli.fullRunnerName
+import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions}
+import scala.cli.commands.tags
 
 // format: off
+@HelpMessage(
+  s"""Generates default files for a $fullRunnerName project (i.e. .gitignore).
+     |
+     |${HelpMessages.commandDocWebsiteReference("misc/default-file")}""".stripMargin)
 final case class DefaultFileOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
   @Group("Default")
   @HelpMessage("Write result to files rather than to stdout")
+  @Tag(tags.restricted)
     write: Boolean = false,
   @Group("Default")
   @HelpMessage("List available default files")
+  @Tag(tags.restricted)
     list: Boolean = false,
   @Group("Default")
   @HelpMessage("List available default file ids")
+  @Tag(tags.restricted)
     listIds: Boolean = false,
   @Group("Default")
   @HelpMessage("Force overwriting destination files")
   @ExtraName("f")
+  @Tag(tags.restricted)
     force: Boolean = false
 ) extends HasLoggingOptions
 // format: on

modules/cli/src/main/scala/scala/cli/commands/default/LegacyScalaOptions.scala

@@ -9,6 +9,7 @@ import scala.cli.ScalaCli.{fullRunnerName, progName}
 import scala.cli.commands.bloop.BloopExit
 import scala.cli.commands.default.LegacyScalaOptions.*
 import scala.cli.commands.package0.Package
+import scala.cli.commands.shared.HelpMessages.PowerString
 import scala.cli.commands.shared.ScalacOptions.YScriptRunnerOption
 import scala.cli.commands.tags
 
@@ -164,9 +165,6 @@ object LegacyScalaOptions {
   implicit lazy val parser: Parser[LegacyScalaOptions] = Parser.derive
   implicit lazy val help: Help[LegacyScalaOptions]     = Help.derive
 
-  private[default] lazy val PowerString =
-    if ScalaCli.allowRestrictedFeatures then "" else "--power "
-
   def yScriptRunnerWarning(yScriptRunnerValue: Option[String]): String = {
     val valueSpecificMsg = yScriptRunnerValue match {
       case Some(v @ "default") =>

modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala

@@ -4,14 +4,16 @@ import caseapp.*
 import caseapp.core.help.Help
 
 import scala.cli.commands.shared.{HasSharedOptions, SharedOptions}
+import scala.cli.commands.tags
 
 // format: off
-@HelpMessage("Update dependencies in project")
+@HelpMessage("Update dependency directives in the project")
 final case class DependencyUpdateOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
   @Group("DependencyUpdate")
-  @HelpMessage("Update all dependencies if newer version was released")
+  @HelpMessage("Update all dependencies if a newer version was released")
+  @Tag(tags.restricted)
     all: Boolean = false,
 ) extends HasSharedOptions
   // format: on

modules/cli/src/main/scala/scala/cli/commands/directories/DirectoriesOptions.scala

@@ -2,10 +2,11 @@ package scala.cli.commands.directories
 
 import caseapp.*
 
+import scala.cli.ScalaCli.fullRunnerName
 import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions}
 
 // format: off
-@HelpMessage("Prints directories used by Scala CLI")
+@HelpMessage(s"Prints directories used by $fullRunnerName.")
 final case class DirectoriesOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions()

modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala

@@ -3,11 +3,20 @@ package scala.cli.commands.doc
 import caseapp.*
 import caseapp.core.help.Help
 
-import scala.cli.commands.shared.{HasSharedOptions, SharedOptions}
+import scala.cli.ScalaCli.fullRunnerName
+import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
 import scala.cli.commands.tags
 
 // format: off
-@HelpMessage("Generate Scaladoc documentation", "By default, Scala CLI sets common scaladoc options and this mechanism can be disabled by using `--default-scaladoc-opts:false`.")
+@HelpMessage(
+  message =
+    s"""Generate Scaladoc documentation.
+       |
+       |${HelpMessages.acceptedInputs}
+       |
+       |${HelpMessages.commandDocWebsiteReference("doc")}""".stripMargin,
+  messageMd = s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`."
+)
 final case class DocOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
@@ -22,7 +31,7 @@ final case class DocOptions(
   @Name("f")
     force: Boolean = false,
   @Group("Doc")
-  @HelpMessage("Control if Scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.")
+  @HelpMessage(s"Control if $fullRunnerName should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.")
   @Tag(tags.should)
   @ExtraName("defaultScaladocOpts")
     defaultScaladocOptions: Option[Boolean] = None,