WIP: supplemental discussion

- IDEA: additional discussion for commands and arguments which is
  exported to dump-help and can be consumed by supplemental content
  generators to contains much more detailed information than you may want
  to include in a help screen.
  Maybe a better idea would be to have --help-detailed flag that would
  include this information in the help output. Suggestions are welcome.

Author: rauhul

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -16,7 +16,11 @@ public struct ArgumentHelp {
 
   /// An expanded description of the argument, in plain text form.
   public var discussion: String = ""
-  
+
+  /// Additional description of the argument for supplemental content, in plain
+  /// text form.
+  public var supplementalDiscussion: String = ""
+
   /// An alternative name to use for the argument's value when showing usage
   /// information.
   ///
@@ -28,41 +32,17 @@ public struct ArgumentHelp {
   /// the extended help display.
   public var visibility: ArgumentVisibility = .default
 
-  /// A Boolean value indicating whether this argument should be shown in
-  /// the extended help display.
-  @available(*, deprecated, message: "Use visibility level instead.")
-  public var shouldDisplay: Bool {
-    get {
-      return visibility.base == .default
-    }
-    set {
-      visibility = newValue ? .default : .hidden
-    }
-  }
-  
-  /// Creates a new help instance.
-  @available(*, deprecated, message: "Use init(_:discussion:valueName:visibility:) instead.")
-  public init(
-    _ abstract: String = "",
-    discussion: String = "",
-    valueName: String? = nil,
-    shouldDisplay: Bool)
-  {
-    self.abstract = abstract
-    self.discussion = discussion
-    self.valueName = valueName
-    self.shouldDisplay = shouldDisplay
-  }
-
   /// Creates a new help instance.
   public init(
     _ abstract: String = "",
     discussion: String = "",
+    supplementalDiscussion: String = "",
     valueName: String? = nil,
     visibility: ArgumentVisibility = .default)
   {
     self.abstract = abstract
     self.discussion = discussion
+    self.supplementalDiscussion = supplementalDiscussion
     self.valueName = valueName
     self.visibility = visibility
   }
@@ -83,3 +63,34 @@ extension ArgumentHelp: ExpressibleByStringInterpolation {
     self.abstract = value
   }
 }
+
+// MARK: - Deprecated API
+extension ArgumentHelp {
+  /// A Boolean value indicating whether this argument should be shown in
+  /// the extended help display.
+  @available(*, deprecated, message: "Use visibility level instead.")
+  public var shouldDisplay: Bool {
+    get {
+      return visibility.base == .default
+    }
+    set {
+      visibility = newValue ? .default : .hidden
+    }
+  }
+
+  /// Creates a new help instance.
+  @available(*, deprecated, message: "Use init(_:discussion:supplementalDiscussion:valueName:visibility:) instead.")
+  public init(
+    _ abstract: String = "",
+    discussion: String = "",
+    valueName: String? = nil,
+    shouldDisplay: Bool)
+  {
+    self.init(
+      abstract,
+      discussion: discussion,
+      supplementalDiscussion: "",
+      valueName: valueName,
+      visibility: shouldDisplay ? .default : .hidden)
+  }
+}

Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift

@@ -38,6 +38,10 @@ public struct CommandConfiguration {
   /// A longer description of this command, to be shown in the extended help
   /// display.
   public var discussion: String
+
+  /// Additional description of this command to be shown in supplemental content
+  /// such as manuals.
+  public var supplementalDiscussion: String
 
   /// Version information for this command.
   public var version: String
@@ -67,6 +71,8 @@ public struct CommandConfiguration {
   ///     automatically generating a usage description. Passing an empty string
   ///     hides the usage string altogether.
   ///   - discussion: A longer description of the command.
+  ///   - supplementalDiscussion: Additional description of the command for
+  ///     supplemental content.
   ///   - version: The version number for this command. When you provide a
   ///     non-empty string, the argument parser prints it if the user provides
   ///     a `--version` flag.
@@ -85,6 +91,7 @@ public struct CommandConfiguration {
     abstract: String = "",
     usage: String? = nil,
     discussion: String = "",
+    supplementalDiscussion: String = "",
     version: String = "",
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
@@ -95,6 +102,7 @@ public struct CommandConfiguration {
     self.abstract = abstract
     self.usage = usage
     self.discussion = discussion
+    self.supplementalDiscussion = supplementalDiscussion
     self.version = version
     self.shouldDisplay = shouldDisplay
     self.subcommands = subcommands
@@ -110,6 +118,7 @@ public struct CommandConfiguration {
     abstract: String = "",
     usage: String? = nil,
     discussion: String = "",
+    supplementalDiscussion: String = "",
     version: String = "",
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
@@ -121,6 +130,7 @@ public struct CommandConfiguration {
     self.abstract = abstract
     self.usage = usage
     self.discussion = discussion
+    self.supplementalDiscussion = ""
     self.version = version
     self.shouldDisplay = shouldDisplay
     self.subcommands = subcommands
@@ -130,7 +140,7 @@ public struct CommandConfiguration {
 }
 
 extension CommandConfiguration {
-  @available(*, deprecated, message: "Use the memberwise initializer with the usage parameter.")
+  @available(*, deprecated, message: "Use the member-wise initializer with the usage parameter.")
   public init(
     commandName: String?,
     abstract: String,
@@ -146,6 +156,32 @@ extension CommandConfiguration {
       abstract: abstract,
       usage: "",
       discussion: discussion,
+      supplementalDiscussion: "",
+      version: version,
+      shouldDisplay: shouldDisplay,
+      subcommands: subcommands,
+      defaultSubcommand: defaultSubcommand,
+      helpNames: helpNames)
+  }
+
+  @available(*, deprecated, message: "Use the member-wise initializer with the extendedDiscussion parameter.")
+  public init(
+    commandName: String?,
+    abstract: String,
+    usage: String,
+    discussion: String,
+    version: String,
+    shouldDisplay: Bool,
+    subcommands: [ParsableCommand.Type],
+    defaultSubcommand: ParsableCommand.Type?,
+    helpNames: NameSpecification?
+  ) {
+    self.init(
+      commandName: commandName,
+      abstract: abstract,
+      usage: usage,
+      discussion: discussion,
+      supplementalDiscussion: "",
       version: version,
       shouldDisplay: shouldDisplay,
       subcommands: subcommands,

Sources/ArgumentParser/Parsing/ArgumentDefinition.swift

@@ -52,6 +52,7 @@ struct ArgumentDefinition {
     var isComposite: Bool
     var abstract: String
     var discussion: String
+    var supplementalDiscussion: String
     var valueName: String
     var visibility: ArgumentVisibility
     var parentTitle: String
@@ -71,6 +72,7 @@ struct ArgumentDefinition {
       self.isComposite = isComposite
       self.abstract = help?.abstract ?? ""
       self.discussion = help?.discussion ?? ""
+      self.supplementalDiscussion = help?.supplementalDiscussion ?? ""
       self.valueName = help?.valueName ?? ""
       self.visibility = help?.visibility ?? .default
       self.parentTitle = ""

Sources/ArgumentParser/Usage/DumpHelpGenerator.swift

@@ -114,6 +114,7 @@ fileprivate extension CommandInfoV0 {
       commandName: command._commandName,
       abstract: command.configuration.abstract,
       discussion: command.configuration.discussion,
+      supplementalDiscussion: command.configuration.supplementalDiscussion,
       defaultSubcommand: defaultSubcommand,
       subcommands: subcommands,
       arguments: arguments)
@@ -135,7 +136,8 @@ fileprivate extension ArgumentInfoV0 {
       defaultValue: argument.help.defaultValue,
       allValues: argument.help.allValues,
       abstract: argument.help.abstract,
-      discussion: argument.help.discussion)
+      discussion: argument.help.discussion,
+      supplementalDiscussion: argument.help.supplementalDiscussion)
   }
 }
 

Sources/ArgumentParserToolInfo/ToolInfo.swift

@@ -51,6 +51,9 @@ public struct CommandInfoV0: Codable, Hashable {
   public var abstract: String?
   /// Extended description of the command's functionality.
   public var discussion: String?
+  /// Additional description of the command's functionality for supplemental
+  /// content.
+  public var supplementalDiscussion: String?
 
   /// Optional name of the subcommand invoked when the command is invoked with
   /// no arguments.
@@ -65,6 +68,7 @@ public struct CommandInfoV0: Codable, Hashable {
     commandName: String,
     abstract: String,
     discussion: String,
+    supplementalDiscussion: String,
     defaultSubcommand: String?,
     subcommands: [CommandInfoV0],
     arguments: [ArgumentInfoV0]
@@ -74,6 +78,7 @@ public struct CommandInfoV0: Codable, Hashable {
     self.commandName = commandName
     self.abstract = abstract.nonEmpty
     self.discussion = discussion.nonEmpty
+    self.supplementalDiscussion = supplementalDiscussion.nonEmpty
 
     self.defaultSubcommand = defaultSubcommand?.nonEmpty
     self.subcommands = subcommands.nonEmpty
@@ -146,6 +151,9 @@ public struct ArgumentInfoV0: Codable, Hashable {
   public var abstract: String?
   /// Extended description of the argument's functionality.
   public var discussion: String?
+  /// Additional description of the argument's functionality for supplemental
+  /// content.
+  public var supplementalDiscussion: String?
 
   public init(
     kind: KindV0,
@@ -159,7 +167,8 @@ public struct ArgumentInfoV0: Codable, Hashable {
     defaultValue: String?,
     allValues: [String]?,
     abstract: String?,
-    discussion: String?
+    discussion: String?,
+    supplementalDiscussion: String?
   ) {
     self.kind = kind
 
@@ -178,5 +187,6 @@ public struct ArgumentInfoV0: Codable, Hashable {
 
     self.abstract = abstract?.nonEmpty
     self.discussion = discussion?.nonEmpty
+    self.supplementalDiscussion = supplementalDiscussion?.nonEmpty
   }
 }

Tests/ArgumentParserUnitTests/HelpGenerationTests+AtArgument.swift

@@ -221,6 +221,7 @@ extension HelpGenerationTests {
       var arg0: A? = nil
     }
 
+    @available(*, deprecated, message: "Included for test coverage")
     struct OptionalDefault: ParsableCommand {
       @Argument(help: "example")
       var arg0: A? = A()

Tests/ArgumentParserUnitTests/HelpGenerationTests+AtOption.swift

@@ -179,6 +179,7 @@ extension HelpGenerationTests {
       var arg0: A? = nil
     }
 
+    @available(*, deprecated, message: "Included for test coverage")
     struct OptionalDefault: ParsableCommand {
       @Option(help: "example")
       var arg0: A? = A()

Tools/generate-manual/DSL/SinglePageDescription.swift renamed to Tools/generate-manual/DSL/Description.swift

@@ -12,7 +12,8 @@
 import ArgumentParser
 import ArgumentParserToolInfo
 
-struct SinglePageDescription: MDocComponent {
+struct Description: MDocComponent {
+  var multipage: Bool
   var command: CommandInfoV0
 
   var body: MDocComponent {
@@ -27,6 +28,14 @@ struct SinglePageDescription: MDocComponent {
       discussion
     }
 
+    if command.discussion != nil, command.supplementalDiscussion != nil {
+      MDocMacro.ParagraphBreak()
+    }
+
+    if let supplementalDiscussion = command.supplementalDiscussion {
+      supplementalDiscussion
+    }
+
     List {
       for argument in command.arguments ?? [] {
         MDocMacro.ListItem(title: argument.manualPageDescription)
@@ -42,11 +51,23 @@ struct SinglePageDescription: MDocComponent {
         if let discussion = argument.discussion {
           discussion
         }
+
+        if argument.discussion != nil, argument.supplementalDiscussion != nil {
+          MDocMacro.ParagraphBreak()
+        }
+
+        if let supplementalDiscussion = argument.supplementalDiscussion {
+          supplementalDiscussion
+        }
       }
 
-      for subcommand in command.subcommands ?? [] {
-        MDocMacro.ListItem(title: MDocMacro.Emphasis(arguments: [subcommand.commandName]))
-        SinglePageDescription(command: subcommand).core
+      if !multipage {
+        for subcommand in command.subcommands ?? [] {
+          MDocMacro.ListItem(title: MDocMacro.Emphasis(arguments: [subcommand.commandName]))
+          Description(
+            multipage: multipage,
+            command: subcommand).core
+        }
       }
     }
   }

Tools/generate-manual/DSL/Document.swift

@@ -24,11 +24,7 @@ struct Document: MDocComponent {
     Preamble(date: date, section: section, command: command)
     Name(command: command)
     Synopsis(command: command)
-    if multiPage {
-      MultiPageDescription(command: command)
-    } else {
-      SinglePageDescription(command: command)
-    }
+    Description(multipage: multiPage, command: command)
     Exit(section: section)
     if multiPage {
       SeeAlso(section: section, command: command)