Skip to content

Commit d79446b

Browse files
authored
Shorter options help (#1872)
* NIT Refactor SpecificationLevel * Bump `case-app` to `2.1.0-M24` & `scala-cli-signing` to `0.1.16` * Limit short `--help` options to just `MUST` & `IMPORTANT` tags * Shorten the basic help message for the `run` sub-command * Shorten the basic help message for the `version` sub-command * Tweak the help output for the `update` sub-command * Tweak the help output for the `uninstall completions` sub-command * Tweak the help output for the `test` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `shebang` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `setup-ide` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `repl` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `publish` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `publish setup` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Tweak the help output for the `publish local` sub-command - shorten the help message - tweak which options are included in the short help - misc tweaks * Hide non-publishing-specific options in the short help output for `publish`, `publish local` and `publish setup` sub-commands * Tweak the short help output for the `package` sub-command * Tweak the short help output for the `install-home` sub-command * Tweak the short help output for the `install completions` sub-command * Tweak the short help output for the `github secret list` & `github secret create` sub-commands * Tweak the short help output for the `fmt` sub-command * Tweak the short help output for the `export` sub-command * Tweak the short help output for the `doc` sub-command * Tweak the short help output for the `dependency-update` sub-command * Tweak the short help output for the `config` sub-command * Tweak the short help output for the `compile` sub-command * Tweak the short help output for the `clean` sub-command * Tweak the short help output for the `bsp` sub-command * Tweak the short help output for the `bloop` sub-command * Put the `Help` help group at the end of sorted groups * Adjust help-relevant tests * Adjust `--help-js` and `--help-native` * Apply review comments - temporarily remove console-specific characters from help messages to fix the reference doc website - remove redundant tags for options already tagged as `SpecificationLevel.MUST` - rename `tags.important` to `tags.inShortHelp` * Ensure all launcher options are properly tagged * Ensure all `export` options are properly tagged * Fix integration tests after tied with `--power` mode after relevant tags changed
1 parent 648755d commit d79446b

File tree

77 files changed

+1006
-860
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+1006
-860
lines changed

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

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,7 @@ import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessag
66
import scala.cli.commands.tags
77

88
// format: off
9-
@HelpMessage(
10-
s"""Interact with Bloop (the build server) or check its status.
11-
|
12-
|This sub-command allows to check the current status of Bloop.
13-
|If Bloop isn't currently running, it will be started.
14-
|
15-
|${HelpMessages.bloopInfo}""".stripMargin)
9+
@HelpMessage(BloopOptions.helpMessage, "", BloopOptions.detailedHelpMessage)
1610
final case class BloopOptions(
1711
@Recurse
1812
logging: LoggingOptions = LoggingOptions(),
@@ -39,4 +33,12 @@ final case class BloopOptions(
3933
object BloopOptions {
4034
implicit lazy val parser: Parser[BloopOptions] = Parser.derive
4135
implicit lazy val help: Help[BloopOptions] = Help.derive
36+
val helpMessage: String = "Interact with Bloop (the build server) or check its status."
37+
val detailedHelpMessage: String =
38+
s"""$helpMessage
39+
|
40+
|This sub-command allows to check the current status of Bloop.
41+
|If Bloop isn't currently running, it will be started.
42+
|
43+
|${HelpMessages.bloopInfo}""".stripMargin
4244
}

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

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,7 @@ import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
77
import scala.cli.commands.tags
88

99
// format: off
10-
@HelpMessage(
11-
s"""Start BSP server.
12-
|
13-
|BSP stands for Build Server Protocol.
14-
|For more information refer to https://build-server-protocol.github.io/
15-
|
16-
|This sub-command is not designed to be used by a human.
17-
|It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported.
18-
|
19-
|${HelpMessages.docsWebsiteReference}""".stripMargin)
10+
@HelpMessage(BspOptions.helpMessage, "", BspOptions.detailedHelpMessage)
2011
final case class BspOptions(
2112
// FIXME There might be too many options in SharedOptions for the bsp command…
2213
@Recurse
@@ -34,4 +25,21 @@ final case class BspOptions(
3425
object BspOptions {
3526
implicit lazy val parser: Parser[BspOptions] = Parser.derive
3627
implicit lazy val help: Help[BspOptions] = Help.derive
28+
val cmdName = "bsp"
29+
private val helpHeader = "Start BSP server."
30+
val helpMessage: String =
31+
s"""$helpHeader
32+
|
33+
|${HelpMessages.commandFullHelpReference(cmdName)}
34+
|${HelpMessages.docsWebsiteReference}""".stripMargin
35+
val detailedHelpMessage: String =
36+
s"""$helpHeader
37+
|
38+
|BSP stands for Build Server Protocol.
39+
|For more information refer to https://build-server-protocol.github.io/
40+
|
41+
|This sub-command is not designed to be used by a human.
42+
|It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported.
43+
|
44+
|${HelpMessages.docsWebsiteReference}""".stripMargin
3745
}

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

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,7 @@ import scala.cli.commands.shared.{
1212
}
1313

1414
// format: off
15-
@HelpMessage(
16-
s"""Clean the workspace.
17-
|
18-
|Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned.
19-
|
20-
|${HelpMessages.commandDocWebsiteReference("clean")}""".stripMargin)
15+
@HelpMessage(CleanOptions.helpMessage, "", CleanOptions.detailedHelpMessage)
2116
final case class CleanOptions(
2217
@Recurse
2318
logging: LoggingOptions = LoggingOptions(),
@@ -31,4 +26,13 @@ final case class CleanOptions(
3126
object CleanOptions {
3227
implicit lazy val parser: Parser[CleanOptions] = Parser.derive
3328
implicit lazy val help: Help[CleanOptions] = Help.derive
29+
val cmdName = "clean"
30+
private val helpHeader = "Clean the workspace."
31+
val helpMessage: String = HelpMessages.shortHelpMessage(cmdName, helpHeader)
32+
val detailedHelpMessage: String =
33+
s"""$helpHeader
34+
|
35+
|Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned.
36+
|
37+
|${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
3438
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package scala.cli.commands.compile
22

33
import caseapp.*
4+
import caseapp.core.help.HelpFormat
45

56
import java.io.File
67

@@ -14,13 +15,18 @@ import scala.cli.commands.update.Update
1415
import scala.cli.commands.util.BuildCommandHelpers
1516
import scala.cli.commands.{CommandUtils, ScalaCommand, WatchUtil}
1617
import scala.cli.config.{ConfigDb, Keys}
18+
import scala.cli.util.ArgHelpers.*
1719

1820
object Compile extends ScalaCommand[CompileOptions] with BuildCommandHelpers {
1921
override def group = "Main"
2022

2123
override def sharedOptions(options: CompileOptions): Option[SharedOptions] = Some(options.shared)
2224

2325
override def scalaSpecificationLevel = SpecificationLevel.MUST
26+
val primaryHelpGroups: Seq[String] =
27+
Seq("Compilation", "Scala", "Java", "Watch", "Compilation server")
28+
29+
override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroups(primaryHelpGroups)
2430

2531
override def runCommand(options: CompileOptions, args: RemainingArgs, logger: Logger): Unit = {
2632
val buildOptions = buildOptionsOrExit(options)

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

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,7 @@ import scala.cli.commands.shared.{
1212
}
1313
import scala.cli.commands.tags
1414

15-
@HelpMessage({
16-
val cmdName = "compile"
17-
s"""Compile Scala code.
18-
|
19-
|${HelpMessages.commandConfigurations(cmdName)}
20-
|
21-
|${HelpMessages.acceptedInputs}
22-
|
23-
|${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
24-
})
15+
@HelpMessage(CompileOptions.helpMessage, "", CompileOptions.detailedHelpMessage)
2516
// format: off
2617
final case class CompileOptions(
2718
@Recurse
@@ -31,19 +22,34 @@ final case class CompileOptions(
3122
@Recurse
3223
cross: CrossOptions = CrossOptions(),
3324

25+
@Group("Compilation")
3426
@Name("p")
3527
@Name("printClasspath")
3628
@HelpMessage("Print the resulting class path")
3729
@Tag(tags.should)
30+
@Tag(tags.inShortHelp)
3831
printClassPath: Boolean = false,
3932

33+
@Group("Compilation")
4034
@HelpMessage("Compile test scope")
4135
@Tag(tags.should)
36+
@Tag(tags.inShortHelp)
4237
test: Boolean = false
4338
) extends HasSharedOptions
4439
// format: on
4540

4641
object CompileOptions {
4742
implicit lazy val parser: Parser[CompileOptions] = Parser.derive
4843
implicit lazy val help: Help[CompileOptions] = Help.derive
44+
val cmdName = "compile"
45+
private val helpHeader = "Compile Scala code."
46+
val helpMessage: String = HelpMessages.shortHelpMessage(cmdName, helpHeader)
47+
val detailedHelpMessage: String =
48+
s"""$helpHeader
49+
|
50+
|${HelpMessages.commandConfigurations(cmdName)}
51+
|
52+
|${HelpMessages.acceptedInputs}
53+
|
54+
|${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
4955
}

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

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package scala.cli.commands.config
22

33
import caseapp.core.RemainingArgs
4+
import caseapp.core.help.HelpFormat
45
import coursier.cache.ArchiveCache
56

67
import java.util.Base64
@@ -20,11 +21,14 @@ import scala.cli.config.{
2021
RepositoryCredentials,
2122
Secret
2223
}
23-
24+
import scala.cli.util.ArgHelpers.*
2425
object Config extends ScalaCommand[ConfigOptions] {
25-
override def hidden = true
2626
override def scalaSpecificationLevel = SpecificationLevel.MUST
2727

28+
override def helpFormat: HelpFormat = super.helpFormat
29+
.copy(hiddenGroups = Some(Seq("Java")))
30+
.withPrimaryGroup("Config")
31+
2832
override def runCommand(options: ConfigOptions, args: RemainingArgs, logger: Logger): Unit = {
2933
val directories = Directories.directories
3034

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

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,7 @@ import scala.cli.commands.shared.{
1414
import scala.cli.commands.tags
1515

1616
// format: off
17-
@HelpMessage(
18-
s"""Configure global settings for $fullRunnerName.
19-
|
20-
|Syntax:
21-
| $progName config key value
22-
|For example, to globally set the interactive mode:
23-
| $progName config interactive true
24-
|
25-
|${HelpMessages.commandDocWebsiteReference("misc/config")}""".stripMargin)
17+
@HelpMessage(ConfigOptions.helpMessage, "", ConfigOptions.detailedHelpMessage)
2618
final case class ConfigOptions(
2719
@Recurse
2820
logging: LoggingOptions = LoggingOptions(),
@@ -37,46 +29,75 @@ final case class ConfigOptions(
3729
@HelpMessage("Dump config DB as JSON")
3830
@Hidden
3931
@Tag(tags.implementation)
32+
@Tag(tags.inShortHelp)
4033
dump: Boolean = false,
4134
@Group("Config")
4235
@HelpMessage("Create PGP key in config")
36+
@Tag(tags.inShortHelp)
37+
@Tag(tags.restricted)
4338
createPgpKey: Boolean = false,
4439
@Group("Config")
4540
@HelpMessage("Email to use to create PGP key in config")
4641
@Tag(tags.restricted)
42+
@Tag(tags.inShortHelp)
4743
email: Option[String] = None,
4844
@Group("Config")
4945
@HelpMessage("If the entry is a password, print the password value rather than how to get the password")
5046
@Tag(tags.restricted)
47+
@Tag(tags.inShortHelp)
5148
password: Boolean = false,
5249
@Group("Config")
5350
@HelpMessage("If the entry is a password, save the password value rather than how to get the password")
5451
@Tag(tags.restricted)
52+
@Tag(tags.inShortHelp)
5553
passwordValue: Boolean = false,
5654
@Group("Config")
5755
@HelpMessage("Remove an entry from config")
56+
@Tag(tags.inShortHelp)
57+
@Tag(tags.should)
5858
@ExtraName("remove")
5959
unset: Boolean = false,
6060
@Group("Config")
6161
@HelpMessage("For repository.credentials and publish.credentials, whether these credentials should be HTTPS only (default: true)")
6262
@Tag(tags.restricted)
63+
@Tag(tags.inShortHelp)
6364
httpsOnly: Option[Boolean] = None,
6465
@Group("Config")
6566
@HelpMessage("For repository.credentials, whether to use these credentials automatically based on the host")
6667
@Tag(tags.restricted)
68+
@Tag(tags.inShortHelp)
6769
matchHost: Option[Boolean] = None,
6870
@Group("Config")
6971
@HelpMessage("For repository.credentials, whether to use these credentials are optional")
7072
@Tag(tags.restricted)
73+
@Tag(tags.inShortHelp)
7174
optional: Option[Boolean] = None,
7275
@Group("Config")
7376
@HelpMessage("For repository.credentials, whether to use these credentials should be passed upon redirection")
7477
@Tag(tags.restricted)
78+
@Tag(tags.inShortHelp)
7579
passOnRedirect: Option[Boolean] = None
7680
) extends HasLoggingOptions
7781
// format: on
7882

7983
object ConfigOptions {
8084
implicit lazy val parser: Parser[ConfigOptions] = Parser.derive
8185
implicit lazy val help: Help[ConfigOptions] = Help.derive
86+
private val helpHeader: String = s"Configure global settings for $fullRunnerName."
87+
private val cmdName = "config"
88+
private val websiteSuffix = s"misc/$cmdName"
89+
val helpMessage: String =
90+
s"""$helpHeader
91+
|
92+
|${HelpMessages.commandFullHelpReference(cmdName)}
93+
|${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
94+
val detailedHelpMessage: String =
95+
s"""$helpHeader
96+
|
97+
|Syntax:
98+
| $progName $cmdName key value
99+
|For example, to globally set the interactive mode:
100+
| $progName $cmdName interactive true
101+
|
102+
|${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
82103
}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package scala.cli.commands.dependencyupdate
22

33
import caseapp.*
4+
import caseapp.core.help.HelpFormat
45

56
import scala.build.actionable.ActionableDependencyHandler
67
import scala.build.actionable.ActionableDiagnostic.ActionableDependencyUpdateDiagnostic
@@ -10,10 +11,12 @@ import scala.build.{CrossSources, Logger, Position, Sources}
1011
import scala.cli.CurrentParams
1112
import scala.cli.commands.ScalaCommand
1213
import scala.cli.commands.shared.SharedOptions
14+
import scala.cli.util.ArgHelpers.*
1315

1416
object DependencyUpdate extends ScalaCommand[DependencyUpdateOptions] {
1517
override def group = "Main"
1618
override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
19+
override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroup("Dependency")
1720
override def sharedOptions(options: DependencyUpdateOptions): Option[SharedOptions] =
1821
Some(options.shared)
1922
override def runCommand(

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ import scala.cli.commands.tags
1111
final case class DependencyUpdateOptions(
1212
@Recurse
1313
shared: SharedOptions = SharedOptions(),
14-
@Group("DependencyUpdate")
14+
@Group("Dependency")
1515
@HelpMessage("Update all dependencies if a newer version was released")
1616
@Tag(tags.restricted)
17+
@Tag(tags.inShortHelp)
1718
all: Boolean = false,
1819
) extends HasSharedOptions
1920
// format: on

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package scala.cli.commands.doc
22

33
import caseapp.*
4+
import caseapp.core.help.HelpFormat
45
import dependency.*
56

67
import java.io.File
@@ -18,13 +19,16 @@ import scala.cli.commands.shared.SharedOptions
1819
import scala.cli.commands.{CommandUtils, ScalaCommand}
1920
import scala.cli.config.{ConfigDb, Keys}
2021
import scala.cli.errors.ScaladocGenerationFailedError
22+
import scala.cli.util.ArgHelpers.*
2123
import scala.util.Properties
2224

2325
object Doc extends ScalaCommand[DocOptions] {
2426
override def group = "Main"
2527

2628
override def sharedOptions(options: DocOptions): Option[SharedOptions] = Some(options.shared)
2729

30+
override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroup("Doc")
31+
2832
override def scalaSpecificationLevel = SpecificationLevel.MUST
2933

3034
override def runCommand(options: DocOptions, args: RemainingArgs, logger: Logger): Unit = {

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

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,7 @@ import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
88
import scala.cli.commands.tags
99

1010
// format: off
11-
@HelpMessage(
12-
message =
13-
s"""Generate Scaladoc documentation.
14-
|
15-
|${HelpMessages.acceptedInputs}
16-
|
17-
|${HelpMessages.commandDocWebsiteReference("doc")}""".stripMargin,
18-
messageMd = s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`."
19-
)
11+
@HelpMessage(DocOptions.helpMessage, DocOptions.messageMd, DocOptions.detailedHelpMessage)
2012
final case class DocOptions(
2113
@Recurse
2214
shared: SharedOptions = SharedOptions(),
@@ -41,4 +33,15 @@ final case class DocOptions(
4133
object DocOptions {
4234
implicit lazy val parser: Parser[DocOptions] = Parser.derive
4335
implicit lazy val help: Help[DocOptions] = Help.derive
36+
val cmdName = "doc"
37+
private val helpHeader = "Generate Scaladoc documentation."
38+
val helpMessage: String = HelpMessages.shortHelpMessage(cmdName, helpHeader)
39+
val detailedHelpMessage: String =
40+
s"""Generate Scaladoc documentation.
41+
|
42+
|${HelpMessages.acceptedInputs}
43+
|
44+
|${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
45+
val messageMd =
46+
s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`."
4447
}

0 commit comments

Comments
 (0)