Updates output to present the string representation of command arguments to a wrapped text block (#791)

heckj · web-flow · commit c3bdeba7aa42 · 2025-08-19T09:54:03.000-07:00
Arguments switched from a single long line within a preformatted text
block to multilines and wrapped to a line length. This makes the output
significantly easier to read when there's a large number of options
(for example, the `swift build` command). The wrapping algorithm is
a simple greedy algorithm that extends up to, but not beyond, a
maximum text width.

The line length defined by the style of output (markdown - 80, docc - 60)
- Snapshot tests for output updated to reflect changes
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md
@@ -28,7 +28,7 @@ This is optional.
 Show subcommand help information.
 
 ```
-color help [<subcommands>...] 
+color help [<subcommands>...]
 ```
 
 - term **subcommands**:
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md
@@ -28,7 +28,7 @@ This is optional.
 Show subcommand help information.
 
 ```
-color help [<subcommands>...] 
+color help [<subcommands>...]
 ```
 
 **subcommands:**
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md
@@ -3,7 +3,8 @@
 <!-- Generated by swift-argument-parser -->
 
 ```
-count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
+count-lines [<input-file>] [--prefix=<prefix>] [--verbose]
+  [--help]
 ```
 
 - term **input-file**:
@@ -31,7 +32,7 @@ count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
 Show subcommand help information.
 
 ```
-count-lines help [<subcommands>...] 
+count-lines help [<subcommands>...]
 ```
 
 - term **subcommands**:
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md
@@ -31,7 +31,7 @@ count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
 Show subcommand help information.
 
 ```
-count-lines help [<subcommands>...] 
+count-lines help [<subcommands>...]
 ```
 
 **subcommands:**
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md
@@ -53,7 +53,8 @@ math add [--hex-output] [<values>...] [--version] [--help]
 Print the product of the values.
 
 ```
-math multiply [--hex-output] [<values>...] [--version] [--help]
+math multiply [--hex-output] [<values>...] [--version]
+  [--help]
 ```
 
 - term **--hex-output**:
@@ -101,7 +102,8 @@ math stats [--version] [--help]
 Print the average of the values.
 
 ```
-math stats average [--kind=<kind>] [<values>...] [--version] [--help]
+math stats average [--kind=<kind>] [<values>...] [--version]
+  [--help]
 ```
 
 - term **--kind=\<kind\>**:
@@ -156,7 +158,12 @@ math stats stdev [<values>...] [--version] [--help]
 Print the quantiles of the values (TBD).
 
 ```
-math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>] [<values>...]     [--file=<file>] [--directory=<directory>] [--shell=<shell>] [--custom=<custom>] [--custom-deprecated=<custom-deprecated>] [--version] [--help]
+math stats quantiles [<one-of-four>] [<custom-arg>]
+  [<custom-deprecated-arg>] [<values>...] [--file=<file>]
+  [--directory=<directory>] [--shell=<shell>]
+  [--custom=<custom>]
+  [--custom-deprecated=<custom-deprecated>] [--version]
+  [--help]
 ```
 
 - term **one-of-four**:
@@ -207,7 +214,7 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>] [<
 Show subcommand help information.
 
 ```
-math help [<subcommands>...]  [--version]
+math help [<subcommands>...] [--version]
 ```
 
 - term **subcommands**:
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md
@@ -156,7 +156,10 @@ math stats stdev [<values>...] [--version] [--help]
 Print the quantiles of the values (TBD).
 
 ```
-math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>] [<values>...]     [--file=<file>] [--directory=<directory>] [--shell=<shell>] [--custom=<custom>] [--custom-deprecated=<custom-deprecated>] [--version] [--help]
+math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>]
+  [<values>...] [--file=<file>] [--directory=<directory>] [--shell=<shell>]
+  [--custom=<custom>] [--custom-deprecated=<custom-deprecated>] [--version]
+  [--help]
 ```
 
 **one-of-four:**
@@ -207,7 +210,7 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>] [<
 Show subcommand help information.
 
 ```
-math help [<subcommands>...]  [--version]
+math help [<subcommands>...] [--version]
 ```
 
 **subcommands:**
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md
@@ -3,7 +3,8 @@
 <!-- Generated by swift-argument-parser -->
 
 ```
-repeat [--count=<count>] [--include-counter] <phrase> [--help]
+repeat [--count=<count>] [--include-counter] <phrase>
+  [--help]
 ```
 
 - term **--count=\<count\>**:
@@ -31,7 +32,7 @@ repeat [--count=<count>] [--include-counter] <phrase> [--help]
 Show subcommand help information.
 
 ```
-repeat help [<subcommands>...] 
+repeat help [<subcommands>...]
 ```
 
 - term **subcommands**:
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md
@@ -31,7 +31,7 @@ repeat [--count=<count>] [--include-counter] <phrase> [--help]
 Show subcommand help information.
 
 ```
-repeat help [<subcommands>...] 
+repeat help [<subcommands>...]
 ```
 
 **subcommands:**
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md
@@ -3,7 +3,8 @@
 <!-- Generated by swift-argument-parser -->
 
 ```
-roll [--times=<n>] [--sides=<m>] [--seed=<seed>] [--verbose] [--help]
+roll [--times=<n>] [--sides=<m>] [--seed=<seed>] [--verbose]
+  [--help]
 ```
 
 - term **--times=\<n\>**:
@@ -38,7 +39,7 @@ Use this option to override the default value of a six-sided die.
 Show subcommand help information.
 
 ```
-roll help [<subcommands>...] 
+roll help [<subcommands>...]
 ```
 
 - term **subcommands**:
diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md
@@ -38,7 +38,7 @@ Use this option to override the default value of a six-sided die.
 Show subcommand help information.
 
 ```
-roll help [<subcommands>...] 
+roll help [<subcommands>...]
 ```
 
 **subcommands:**
diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift
@@ -47,6 +47,14 @@ extension CommandInfoV0 {
       String(repeating: "#", count: path.count + 1)
       + " \(self.doccReferenceTitle)\n\n"
 
+    // sets the max width for generating code blocks of content based
+    // on the style
+    let blockWrapLength: Int =
+      switch markdownStyle {
+      case .docc: 60
+      case .github: 80
+      }
+
     if path.count == 0 {
       result += "<!-- Generated by swift-argument-parser -->\n\n"
     }
@@ -57,8 +65,11 @@ extension CommandInfoV0 {
 
     if let args = self.arguments, args.count != 0 {
       result += "```\n"
+      let commandString = (path + [self.commandName]).joined(separator: " ")
       result +=
-        (path + [self.commandName]).joined(separator: " ") + " " + self.usage()
+        commandString
+        + self.usage(
+          startlength: commandString.count, wraplength: blockWrapLength)
       result += "\n```\n\n"
     }
 
@@ -98,12 +109,34 @@ extension CommandInfoV0 {
     return result
   }
 
-  public func usage() -> String {
+  /// Returns a mutl-line string that presents the arguments for a command.
+  /// - Parameters:
+  ///   - startlength: The starting width of the line this multi-line string appends onto.
+  ///   - wraplength: The maximum width  of the multi-linecode block.
+  /// - Returns: A wrapped, multi-line string that wraps the commands arguments into a text block.
+  public func usage(startlength: Int, wraplength: Int) -> String {
     guard let args = self.arguments else {
       return ""
     }
 
-    return args.map { $0.usage() }.joined(separator: " ")
+    var multilineString = ""
+    // This is a greedy algorithm to wrap the arguments into a
+    // multi-line string that is expected to be returned within
+    // a markdown code block (pre-formatted text).
+    var currentLength = startlength
+    for arg in args where arg.shouldDisplay {
+      let nextUsage = arg.usage()
+      if currentLength + arg.usage().count > wraplength {
+        // the next usage() string exceeds the max width, wrap it.
+        multilineString.append("\n  \(nextUsage)")
+        currentLength = nextUsage.count + 2  // prepend spacing length of 2
+      } else {
+        // the next usage() string doesn't exceed the max width
+        multilineString.append(" \(nextUsage)")
+        currentLength += nextUsage.count + 1
+      }
+    }
+    return multilineString
   }
 }
 
