Print supported values in synopses, when practical

Sources/ArgumentParser/Documentation.docc/Articles/CommandsAndSubcommands.md

@@ -22,7 +22,7 @@ You can build a program with commands and subcommands by defining multiple comma
 % math stats
 OVERVIEW: Calculate descriptive statistics.
 
-USAGE: math stats <subcommand>
+USAGE: math stats <average|stdev|quantiles>
 
 OPTIONS:
   -h, --help              Show help information.
@@ -118,7 +118,7 @@ extension Math.Statistics {
         static let configuration = CommandConfiguration(
             abstract: "Print the average of the values.")
 
-        enum Kind: String, ExpressibleByArgument {
+        enum Kind: String, ExpressibleByArgument, CaseIterable {
             case mean, median, mode
         }
 

Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md

@@ -102,7 +102,7 @@ struct FruitStore: ParsableCommand {
 The help screen includes the list of values in the description of the `<fruit>` argument:
 
 ```
-USAGE: fruit-store <fruit> [--quantity <quantity>]
+USAGE: fruit-store <apple|banana|coconut|dragon-fruit> [--quantity <quantity>]
 
 ARGUMENTS:
   <fruit>                 The fruit to purchase (values: apple, banana,
@@ -137,7 +137,7 @@ struct FruitStore: ParsableCommand {
 The help screen still contains all the possible values.
 
 ```
-USAGE: fruit-store <fruit> [--quantity <quantity>]
+USAGE: fruit-store <apple|banana|coconut|dragon-fruit> [--quantity <quantity>]
 
 ARGUMENTS:
   <fruit>                 The fruit to purchase (values: apple, banana,

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -111,9 +111,15 @@ internal struct HelpGenerator {
     } else {
       var usage = UsageGenerator(toolName: toolName, definition: [currentArgSet])
         .synopsis
-      if !currentCommand.configuration.subcommands.isEmpty {
+      let subcommands = currentCommand.configuration.subcommands.filter { $0.configuration.shouldDisplay }
+      if !subcommands.isEmpty {
         if usage.last != " " { usage += " " }
-        usage += "<subcommand>"
+        let joinedSubcommands = subcommands.map { $0._commandName }.joined(separator: "|")
+        if subcommands.count > 1 && joinedSubcommands.count <= 40 {
+          usage += "<\(joinedSubcommands)>"
+        } else {
+          usage += "<subcommand>"
+        }
       }
       self.usage = usage
     }

Sources/ArgumentParser/Usage/UsageGenerator.swift

@@ -104,12 +104,22 @@ extension ArgumentDefinition {
 
       switch update {
       case .unary:
-        return "\(name.synopsisString) <\(valueName)>"
+        let joinedValues = help.allValueStrings.joined(separator: "|")
+        if help.allValueStrings.count > 1 && joinedValues.count <= 40 {
+          return "\(name.synopsisString) <\(joinedValues)>"
+        } else {
+          return "\(name.synopsisString) <\(valueName)>"
+        }
       case .nullary:
         return name.synopsisString
       }
     case .positional:
-      return "<\(valueName)>"
+      let joinedValues = help.allValueStrings.joined(separator: "|")
+      if help.allValueStrings.count > 1 && joinedValues.count <= 40 {
+        return "<\(joinedValues)>"
+      } else {
+        return "<\(valueName)>"
+      }
     case .default:
       return ""
     }

Tests/ArgumentParserEndToEndTests/SubcommandEndToEndTests.swift

@@ -71,7 +71,7 @@ extension SubcommandEndToEndTests {
     let helpB = Foo.message(for: CleanExit.helpRequest(CommandB.self))
 
     AssertEqualStrings(actual: helpFoo, expected: """
-            USAGE: foo --name <name> <subcommand>
+            USAGE: foo --name <name> <a|b>
 
             OPTIONS:
               --name <name>

Tests/ArgumentParserExampleTests/MathExampleTests.swift

@@ -29,7 +29,7 @@ final class MathExampleTests: XCTestCase {
     let helpText = """
         OVERVIEW: A utility for performing maths.
 
-        USAGE: math <subcommand>
+        USAGE: math <add|multiply|stats>
 
         OPTIONS:
           --version               Show the version.
@@ -73,11 +73,33 @@ final class MathExampleTests: XCTestCase {
     try AssertExecuteCommand(command: "math help add --help", expected: helpText)
   }
 
+  func testMath_StatsHelp() throws {
+    let helpText = """
+        OVERVIEW: Calculate descriptive statistics.
+
+        USAGE: math stats <average|stdev|quantiles>
+
+        OPTIONS:
+          --version               Show the version.
+          -h, --help              Show help information.
+
+        SUBCOMMANDS:
+          average                 Print the average of the values.
+          stdev                   Print the standard deviation of the values.
+          quantiles               Print the quantiles of the values (TBD).
+
+          See 'math help stats <subcommand>' for detailed help.
+        """
+    try AssertExecuteCommand(command: "math stats -h", expected: helpText)
+    try AssertExecuteCommand(command: "math stats --help", expected: helpText)
+    try AssertExecuteCommand(command: "math help stats", expected: helpText)
+  }
+
   func testMath_StatsMeanHelp() throws {
     let helpText = """
         OVERVIEW: Print the average of the values.
 
-        USAGE: math stats average [--kind <kind>] [<values> ...]
+        USAGE: math stats average [--kind <mean|median|mode>] [<values> ...]
 
         ARGUMENTS:
           <values>                A group of floating-point values to operate on.
@@ -128,7 +150,7 @@ final class MathExampleTests: XCTestCase {
       command: "math stats average --kind mode",
       expected: """
             Error: Please provide at least one value to calculate the mode.
-            Usage: math stats average [--kind <kind>] [<values> ...]
+            Usage: math stats average [--kind <mean|median|mode>] [<values> ...]
               See 'math stats average --help' for more information.
             """,
       exitCode: .validationFailure)

Tests/ArgumentParserPackageManagerTests/HelpTests.swift

@@ -50,7 +50,7 @@ extension HelpTests {
     XCTAssertEqual(
       getErrorText(Package.self, ["help"]).trimmingLines(),
       """
-                USAGE: package <subcommand>
+                USAGE: package <clean|config|describe|generate-xcodeproj>
 
                 OPTIONS:
                   -h, --help              Show help information.
@@ -69,7 +69,7 @@ extension HelpTests {
     XCTAssertEqual(
       Package.message(for: CleanExit.helpRequest()).trimmingLines(),
       """
-                USAGE: package <subcommand>
+                USAGE: package <clean|config|describe|generate-xcodeproj>
 
                 OPTIONS:
                   -h, --help              Show help information.
@@ -97,7 +97,7 @@ extension HelpTests {
     XCTAssertEqual(
       getErrorText(Package.self, ["help", "config"], screenWidth: 80).trimmingLines(),
       """
-                USAGE: package config <subcommand>
+                USAGE: package config <get-mirror|set-mirror|unset-mirror>
 
                 OPTIONS:
                   -h, --help              Show help information.

Tests/ArgumentParserUnitTests/HelpGenerationTests+ExpandedSynopses.swift

@@ -0,0 +1,68 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+import XCTest
+import ArgumentParserTestHelpers
+@testable import ArgumentParser
+
+extension HelpGenerationTests {
+  enum Fruit: String, ExpressibleByArgument, CaseIterable {
+    case apple, banana, coconut, dragonFruit = "dragon-fruit", elderberry, fig, grape, honeydew
+  }
+
+  enum Action: String, ExpressibleByArgument, CaseIterable {
+    case purchase, sample, refund = "return"
+  }
+
+  enum Count: Int, ExpressibleByArgument, CaseIterable {
+    case zero, one, two, three, four, five, six, seven, eight, nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen, seventeen, eighteen, nineteen, twenty
+  }
+
+  enum Ripeness: String, ExpressibleByArgument, CaseIterable {
+    case under, perfect, over
+  }
+
+  struct FruitStore: ParsableArguments {
+    @Argument(help: "The transaction type")
+    var action: Action = .purchase
+
+    @Argument(help: "The fruit to purchase")
+    var fruit: Fruit
+
+    @Option(help: "The number of fruit to purchase")
+    var quantity: Count = .one
+
+    @Option(help: "The desired ripeness of fruit")
+    var ripeness: Ripeness = .perfect
+  }
+
+  func testFruitStoreHelp() {
+    AssertHelp(.default, for: FruitStore.self, equals: """
+            USAGE: fruit_store [<purchase|sample|return>] <fruit> [--quantity <quantity>] [--ripeness <under|perfect|over>]
+
+            ARGUMENTS:
+              <action>                The transaction type (values: purchase, sample,
+                                      return; default: purchase)
+              <fruit>                 The fruit to purchase (values: apple, banana,
+                                      coconut, dragon-fruit, elderberry, fig, grape,
+                                      honeydew)
+
+            OPTIONS:
+              --quantity <quantity>   The number of fruit to purchase (values: 0, 1, 2, 3,
+                                      4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18,
+                                      19, 20; default: 1)
+              --ripeness <ripeness>   The desired ripeness of fruit (values: under,
+                                      perfect, over; default: perfect)
+              -h, --help              Show help information.
+
+            """)
+  }
+}

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -197,7 +197,7 @@ extension HelpGenerationTests {
 
   func testHelpWithDefaultValues() {
     AssertHelp(.default, for: D.self, equals: """
-      USAGE: d [<occupation>] [--name <name>] [--age <age>] [--logging <logging>] [--lucky <numbers> ...] [--optional] [--required] [--degree <degree>] [--directory <directory>] [--manual <manual>] [--unspecial <unspecial>] [--special <special>]
+      USAGE: d [<occupation>] [--name <name>] [--age <age>] [--logging <logging>] [--lucky <numbers> ...] [--optional] [--required] [--degree <degree>] [--directory <directory>] [--manual <manual>] [--unspecial <0|1>] [--special <Apple|Banana>]
 
       ARGUMENTS:
         <occupation>            Your occupation. (default: --)