Add an optional abstract to command groups

Author: DougGregor

Sources/ArgumentParser/Parsable Types/CommandGroup.swift

@@ -14,15 +14,21 @@ public struct CommandGroup: Sendable {
   /// The name of the command group that will be displayed in help.
   public let name: String
 
+  /// A short description of the commands in this group, which will be
+  /// displayed in help.
+  public let abstract: String?
+
   /// The list of subcommands that are part of this group.
   public let subcommands: [ParsableCommand.Type]
 
   /// Create a command group.
   public init(
     name: String,
+    abstract: String? = nil,
     @CommandsBuilder subcommands: () -> [ParsableCommand.Type]
   ) {
     self.name = name
+    self.abstract = abstract
     self.subcommands = subcommands()
   }
 }

Sources/ArgumentParser/Usage/HelpGenerator.swift

@@ -52,7 +52,7 @@ internal struct HelpGenerator {
       case subcommands
       case options
       case title(String)
-      case groupedSubcommands(String)
+      case groupedSubcommands(String, String?)
 
       var description: String {
         switch self {
@@ -64,10 +64,19 @@ internal struct HelpGenerator {
           return "Options"
         case .title(let name):
           return name
-        case .groupedSubcommands(let name):
+        case .groupedSubcommands(let name, _):
           return "\(name) Subcommands"
         }
       }
+
+      var abstract: String? {
+        switch self {
+        case .positionalArguments, .subcommands, .options, .title:
+          return nil
+        case .groupedSubcommands(_, let abstract):
+          return abstract
+        }
+      }
     }
 
     var header: Header
@@ -79,8 +88,14 @@ internal struct HelpGenerator {
       guard !elements.isEmpty else { return "" }
 
       let renderedElements = elements.map { $0.rendered(screenWidth: screenWidth) }.joined()
-      return "\(String(describing: header).uppercased()):\n"
-        + renderedElements
+
+      var renderedHeader = String(describing: header).uppercased() + ":"
+      if let abstract = header.abstract {
+        renderedHeader += " "
+        renderedHeader += abstract.wrapped(to: screenWidth)
+      }
+
+      return renderedHeader + "\n" + renderedElements
     }
   }
 
@@ -217,7 +232,8 @@ internal struct HelpGenerator {
 
     // Create section for a grouping of subcommands.
     func subcommandSection(
-      header: Section.Header, 
+      header: Section.Header,
+      abstract: String? = nil,
       subcommands: [ParsableCommand.Type]
     ) -> Section {
       let subcommandElements: [Section.Element] =
@@ -235,7 +251,10 @@ internal struct HelpGenerator {
             abstract: command.configuration.abstract)
       }
 
-      return Section(header: header, elements: subcommandElements)
+      return Section(
+        header: header,
+        elements: subcommandElements
+      )
     }
 
     // Sections for all of the grouped subcommands.
@@ -247,7 +266,7 @@ internal struct HelpGenerator {
 
         case .group(let group):
           return subcommandSection(
-            header: .groupedSubcommands(group.name),
+            header: .groupedSubcommands(group.name, group.abstract),
             subcommands: group.subcommands
           )
         }

Tests/ArgumentParserUnitTests/HelpGenerationTests.swift

@@ -519,7 +519,10 @@ extension HelpGenerationTests {
     static let configuration = CommandConfiguration(
       commandName: "subgroupings"
     ) {
-      CommandGroup(name: "Broken") {
+      CommandGroup(
+        name: "Broken",
+        abstract: "These commands are currently non-functional due to XYZ."
+      ) {
         Foo.self
         Bar.self
       }
@@ -533,7 +536,7 @@ extension HelpGenerationTests {
   }
 
   func testHelpSubcommandGroups() throws {
-    AssertHelp(.default, for: WithSubgroups.self, equals: """
+    AssertHelp(.default, for: WithSubgroups.self, columns: 50, equals: """
     USAGE: subgroupings <subcommand>
 
     OPTIONS:
@@ -542,7 +545,8 @@ extension HelpGenerationTests {
     SUBCOMMANDS:
       m
 
-    BROKEN SUBCOMMANDS:
+    BROKEN SUBCOMMANDS: These commands are currently non-functional due
+    to XYZ.
       foo                     Perform some foo
       bar                     Perform bar operations