display arguments as term lists in docc-flavored markdown generation (#754)

* display arguments as term lists in docc-flavored markdown generation

- added a Boolean to distinguish regular (GH-flavored) markdown from docc-flavored
  markdown
- represent the arguments in generated files with term lists for the
  docc-flavored variant
- updated the snapshot tests to work both GH and DocC flavored markdown
  generation
- removed an added "\n" in the recording of content for snapshot tests,
  which caused the snapshot tests some issues (recorded tests with new
  values wouldn't pass on second-run)

* applying formatting using Script/format

* resolve soundness check issue for throwing function

* switches argument to --style, defaulting to github flavored markdown, and accepting as 'docc' as an alternative

* adding comments for future-me to understand flow in generate manual to match generate reference

Author: heckj

Sources/ArgumentParserTestHelpers/TestHelpers.swift

@@ -448,7 +448,7 @@ extension XCTest {
       ProcessInfo.processInfo.environment["RECORD_SNAPSHOTS"] != nil
 
     if record || recordEnvironment || !snapshotExists {
-      let recordedValue = actual + "\n"
+      let recordedValue = actual
       try FileManager.default.createDirectory(
         at: snapshotDirectoryURL,
         withIntermediateDirectories: true,
@@ -507,8 +507,9 @@ extension XCTest {
       line: line)
   }
 
-  public func assertGenerateDoccReference(
+  public func assertGeneratedReference(
     command: String,
+    doccFlavored: Bool,
     record: Bool = false,
     test: StaticString = #function,
     file: StaticString = #filePath,
@@ -519,10 +520,19 @@ extension XCTest {
     #endif
 
     let commandURL = debugURL.appendingPathComponent(command)
-    let command = [
-      "generate-docc-reference", commandURL.path,
-      "--output-directory", "-",
-    ]
+    let command: [String]
+    if doccFlavored {
+      command = [
+        "generate-docc-reference", commandURL.path,
+        "--output-directory", "-",
+        "--style", "docc",
+      ]
+    } else {
+      command = [
+        "generate-docc-reference", commandURL.path,
+        "--output-directory", "-",
+      ]
+    }
     let actual = try AssertExecuteCommand(
       command: command,
       file: file,

Tests/ArgumentParserGenerateDoccReferenceTests/GenerateDoccReferenceTests.swift

@@ -14,25 +14,42 @@ import XCTest
 
 final class GenerateDoccReferenceTests: XCTestCase {
   #if os(macOS)
+  func testCountLinesMarkdownReference() throws {
+    guard #available(macOS 12, *) else { return }
+    try assertGeneratedReference(command: "count-lines", doccFlavored: false)
+  }
+
   func testCountLinesDoccReference() throws {
     guard #available(macOS 12, *) else { return }
-    try assertGenerateDoccReference(command: "count-lines")
+    try assertGeneratedReference(command: "count-lines", doccFlavored: true)
   }
   #endif
 
+  func testColorMarkdownReference() throws {
+    try assertGeneratedReference(command: "color", doccFlavored: false)
+  }
   func testColorDoccReference() throws {
-    try assertGenerateDoccReference(command: "color")
+    try assertGeneratedReference(command: "color", doccFlavored: true)
   }
 
+  func testMathMarkdownReference() throws {
+    try assertGeneratedReference(command: "math", doccFlavored: false)
+  }
   func testMathDoccReference() throws {
-    try assertGenerateDoccReference(command: "math")
+    try assertGeneratedReference(command: "math", doccFlavored: true)
   }
 
+  func testRepeatMarkdownReference() throws {
+    try assertGeneratedReference(command: "repeat", doccFlavored: false)
+  }
   func testRepeatDoccReference() throws {
-    try assertGenerateDoccReference(command: "repeat")
+    try assertGeneratedReference(command: "repeat", doccFlavored: true)
   }
 
+  func testRollMarkdownReference() throws {
+    try assertGeneratedReference(command: "roll", doccFlavored: false)
+  }
   func testRollDoccReference() throws {
-    try assertGenerateDoccReference(command: "roll")
+    try assertGeneratedReference(command: "roll", doccFlavored: true)
   }
 }

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md

@@ -6,19 +6,19 @@
 color --fav=<fav> [--second=<second>] [--help]
 ```
 
-**--fav=\<fav\>:**
+- term **--fav=\<fav\>:**
 
 *Your favorite color.*
 
 
-**--second=\<second\>:**
+- term **--second=\<second\>:**
 
 *Your second favorite color.*
 
 This is optional.
 
 
-**--help:**
+- term **--help:**
 
 *Show help information.*
 
@@ -31,7 +31,7 @@ Show subcommand help information.
 color help [<subcommands>...] 
 ```
 
-**subcommands:**
+- term **subcommands:**
 
 
 

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md

@@ -0,0 +1,39 @@
+# color
+
+<!-- Generated by swift-argument-parser -->
+
+```
+color --fav=<fav> [--second=<second>] [--help]
+```
+
+**--fav=\<fav\>:**
+
+*Your favorite color.*
+
+
+**--second=\<second\>:**
+
+*Your second favorite color.*
+
+This is optional.
+
+
+**--help:**
+
+*Show help information.*
+
+
+## color.help
+
+Show subcommand help information.
+
+```
+color help [<subcommands>...] 
+```
+
+**subcommands:**
+
+
+
+
+

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md

@@ -6,22 +6,22 @@
 count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
 ```
 
-**input-file:**
+- term **input-file:**
 
 *A file to count lines in. If omitted, counts the lines of stdin.*
 
 
-**--prefix=\<prefix\>:**
+- term **--prefix=\<prefix\>:**
 
 *Only count lines with this prefix.*
 
 
-**--verbose:**
+- term **--verbose:**
 
 *Include extra information in the output.*
 
 
-**--help:**
+- term **--help:**
 
 *Show help information.*
 
@@ -34,7 +34,7 @@ Show subcommand help information.
 count-lines help [<subcommands>...] 
 ```
 
-**subcommands:**
+- term **subcommands:**
 
 
 

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md

@@ -0,0 +1,42 @@
+# count-lines
+
+<!-- Generated by swift-argument-parser -->
+
+```
+count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
+```
+
+**input-file:**
+
+*A file to count lines in. If omitted, counts the lines of stdin.*
+
+
+**--prefix=\<prefix\>:**
+
+*Only count lines with this prefix.*
+
+
+**--verbose:**
+
+*Include extra information in the output.*
+
+
+**--help:**
+
+*Show help information.*
+
+
+## count-lines.help
+
+Show subcommand help information.
+
+```
+count-lines help [<subcommands>...] 
+```
+
+**subcommands:**
+
+
+
+
+