update verbiage

Author: rauhul

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

@@ -1,6 +1,6 @@
 # Customizing Help for Commands
 
-Define your command's abstract, extended discussion, or usage string, and set the flags used to invoke the help display.
+Define your command's abstract, discussion, or usage string, and set the flags used to invoke the help display.
 
 ## Overview
 

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -17,9 +17,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 = ""
+  /// Additional detailed description of the argument, in plain text form.
+  ///
+  /// This discussion is shown in the detailed help display and supplemental
+  /// content such as generated manuals.
+  public var detailedDiscussion: String = ""
 
   /// An alternative name to use for the argument's value when showing usage
   /// information.
@@ -36,13 +38,13 @@ public struct ArgumentHelp {
   public init(
     _ abstract: String = "",
     discussion: String = "",
-    supplementalDiscussion: String = "",
+    detailedDiscussion: String = "",
     valueName: String? = nil,
     visibility: ArgumentVisibility = .default)
   {
     self.abstract = abstract
     self.discussion = discussion
-    self.supplementalDiscussion = supplementalDiscussion
+    self.detailedDiscussion = detailedDiscussion
     self.valueName = valueName
     self.visibility = visibility
   }
@@ -79,7 +81,7 @@ extension ArgumentHelp {
   }
 
   /// Creates a new help instance.
-  @available(*, deprecated, message: "Use init(_:discussion:supplementalDiscussion:valueName:visibility:) instead.")
+  @available(*, deprecated, message: "Use init(_:discussion:detailedDiscussion:valueName:visibility:) instead.")
   public init(
     _ abstract: String = "",
     discussion: String = "",
@@ -89,7 +91,7 @@ extension ArgumentHelp {
     self.init(
       abstract,
       discussion: discussion,
-      supplementalDiscussion: "",
+      detailedDiscussion: "",
       valueName: valueName,
       visibility: shouldDisplay ? .default : .hidden)
   }

Sources/ArgumentParser/Parsable Types/CommandConfiguration.swift

@@ -39,9 +39,9 @@ public struct CommandConfiguration {
   /// display.
   public var discussion: String
 
-  /// Additional description of this command to be shown in supplemental content
-  /// such as manuals.
-  public var supplementalDiscussion: String
+  /// Additional detailed description of the argument to be shown in the
+  /// detailed help display and supplemental content such as generated manuals.
+  public var detailedDiscussion: String
 
   /// Version information for this command.
   public var version: String
@@ -71,8 +71,9 @@ 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.
+  ///   - detailedDiscussion: Additional detailed description to be shown in the
+  ///     detailed help display and supplemental content such as generated
+  ///     manuals.
   ///   - 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.
@@ -91,7 +92,7 @@ public struct CommandConfiguration {
     abstract: String = "",
     usage: String? = nil,
     discussion: String = "",
-    supplementalDiscussion: String = "",
+    detailedDiscussion: String = "",
     version: String = "",
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
@@ -102,7 +103,7 @@ public struct CommandConfiguration {
     self.abstract = abstract
     self.usage = usage
     self.discussion = discussion
-    self.supplementalDiscussion = supplementalDiscussion
+    self.detailedDiscussion = detailedDiscussion
     self.version = version
     self.shouldDisplay = shouldDisplay
     self.subcommands = subcommands
@@ -118,7 +119,7 @@ public struct CommandConfiguration {
     abstract: String = "",
     usage: String? = nil,
     discussion: String = "",
-    supplementalDiscussion: String = "",
+    detailedDiscussion: String = "",
     version: String = "",
     shouldDisplay: Bool = true,
     subcommands: [ParsableCommand.Type] = [],
@@ -130,7 +131,7 @@ public struct CommandConfiguration {
     self.abstract = abstract
     self.usage = usage
     self.discussion = discussion
-    self.supplementalDiscussion = ""
+    self.detailedDiscussion = ""
     self.version = version
     self.shouldDisplay = shouldDisplay
     self.subcommands = subcommands
@@ -156,15 +157,15 @@ extension CommandConfiguration {
       abstract: abstract,
       usage: "",
       discussion: discussion,
-      supplementalDiscussion: "",
+      detailedDiscussion: "",
       version: version,
       shouldDisplay: shouldDisplay,
       subcommands: subcommands,
       defaultSubcommand: defaultSubcommand,
       helpNames: helpNames)
   }
 
-  @available(*, deprecated, message: "Use the member-wise initializer with the extendedDiscussion parameter.")
+  @available(*, deprecated, message: "Use the member-wise initializer with the detailedDiscussion parameter.")
   public init(
     commandName: String?,
     abstract: String,
@@ -181,7 +182,7 @@ extension CommandConfiguration {
       abstract: abstract,
       usage: usage,
       discussion: discussion,
-      supplementalDiscussion: "",
+      detailedDiscussion: "",
       version: version,
       shouldDisplay: shouldDisplay,
       subcommands: subcommands,

Sources/ArgumentParser/Parsing/ArgumentDefinition.swift

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

Sources/ArgumentParser/Usage/DumpHelpGenerator.swift

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

Sources/ArgumentParserToolInfo/ToolInfo.swift

@@ -53,7 +53,7 @@ public struct CommandInfoV0: Codable, Hashable {
   public var discussion: String?
   /// Additional description of the command's functionality for supplemental
   /// content.
-  public var supplementalDiscussion: String?
+  public var detailedDiscussion: String?
 
   /// Optional name of the subcommand invoked when the command is invoked with
   /// no arguments.
@@ -68,7 +68,7 @@ public struct CommandInfoV0: Codable, Hashable {
     commandName: String,
     abstract: String,
     discussion: String,
-    supplementalDiscussion: String,
+    detailedDiscussion: String,
     defaultSubcommand: String?,
     subcommands: [CommandInfoV0],
     arguments: [ArgumentInfoV0]
@@ -78,7 +78,7 @@ public struct CommandInfoV0: Codable, Hashable {
     self.commandName = commandName
     self.abstract = abstract.nonEmpty
     self.discussion = discussion.nonEmpty
-    self.supplementalDiscussion = supplementalDiscussion.nonEmpty
+    self.detailedDiscussion = detailedDiscussion.nonEmpty
 
     self.defaultSubcommand = defaultSubcommand?.nonEmpty
     self.subcommands = subcommands.nonEmpty
@@ -151,9 +151,11 @@ 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?
+  /// Additional detailed description of the argument's functionality
+  ///
+  /// This discussion is shown in the detailed help display and supplemental
+  /// content such as generated manuals.
+  public var detailedDiscussion: String?
 
   public init(
     kind: KindV0,
@@ -168,7 +170,7 @@ public struct ArgumentInfoV0: Codable, Hashable {
     allValues: [String]?,
     abstract: String?,
     discussion: String?,
-    supplementalDiscussion: String?
+    detailedDiscussion: String?
   ) {
     self.kind = kind
 
@@ -187,6 +189,6 @@ public struct ArgumentInfoV0: Codable, Hashable {
 
     self.abstract = abstract?.nonEmpty
     self.discussion = discussion?.nonEmpty
-    self.supplementalDiscussion = supplementalDiscussion?.nonEmpty
+    self.detailedDiscussion = detailedDiscussion?.nonEmpty
   }
 }

Tools/generate-manual/DSL/Description.swift

@@ -28,12 +28,12 @@ struct Description: MDocComponent {
       discussion
     }
 
-    if command.discussion != nil, command.supplementalDiscussion != nil {
+    if command.discussion != nil, command.detailedDiscussion != nil {
       MDocMacro.ParagraphBreak()
     }
 
-    if let supplementalDiscussion = command.supplementalDiscussion {
-      supplementalDiscussion
+    if let detailedDiscussion = command.detailedDiscussion {
+      detailedDiscussion
     }
 
     List {
@@ -52,12 +52,12 @@ struct Description: MDocComponent {
           discussion
         }
 
-        if argument.discussion != nil, argument.supplementalDiscussion != nil {
+        if argument.discussion != nil, argument.detailedDiscussion != nil {
           MDocMacro.ParagraphBreak()
         }
 
-        if let supplementalDiscussion = argument.supplementalDiscussion {
-          supplementalDiscussion
+        if let detailedDiscussion = argument.detailedDiscussion {
+          detailedDiscussion
         }
       }
 

Tools/generate-manual/GenerateManual.swift

@@ -31,7 +31,7 @@ struct GenerateManual: ParsableCommand {
       using the plugin which can be invoked via \
       `swift package generate-manual`.
       """,
-    supplementalDiscussion: """
+    detailedDiscussion: """
       The generate-manual tool invokes provided executable with the \
       `--experimental-dump-help` argument and decoding the output into a \
       `ToolInfo` structure provided by the `ArgumentParserToolInfo` library. \
@@ -60,7 +60,7 @@ struct GenerateManual: ParsableCommand {
         Manuals for executables are typically included in section 1, but may \
         also be found in other sections such as section 8.
         """,
-      supplementalDiscussion: """
+      detailedDiscussion: """
         A description of manual sections is included below:
         1) General Commands
         2) System Calls