From fcc8f219c369ba56a6299efaa44b8c69c7121928 Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Thu, 3 Apr 2025 18:52:49 +0330 Subject: [PATCH 1/5] [GenerateDocCReference] Improve filtering and categorization of arguments in documentation with sectionTitle --- Sources/ArgumentParserToolInfo/ToolInfo.swift | 18 ++- .../Snapshots/testColorDoccReference().md | 25 ++-- .../testCountLinesDoccReference().md | 29 ++-- .../Snapshots/testMathDoccReference().md | 126 +++++++++--------- .../Snapshots/testRepeatDoccReference().md | 29 ++-- .../Snapshots/testRollDoccReference().md | 35 ++--- .../Snapshots/testADumpHelp().json | 11 ++ .../Snapshots/testBDumpHelp().json | 3 + .../Snapshots/testCDumpHelp().json | 8 ++ .../Snapshots/testMathAddDumpHelp().json | 6 + .../Snapshots/testMathDumpHelp().json | 34 +++++ .../Snapshots/testMathMultiplyDumpHelp().json | 6 + .../Snapshots/testMathStatsDumpHelp().json | 24 ++++ .../Extensions/ArgumentParser+Markdown.swift | 71 ++++++++-- 14 files changed, 298 insertions(+), 127 deletions(-) diff --git a/Sources/ArgumentParserToolInfo/ToolInfo.swift b/Sources/ArgumentParserToolInfo/ToolInfo.swift index 926bb5156..0b3f23190 100644 --- a/Sources/ArgumentParserToolInfo/ToolInfo.swift +++ b/Sources/ArgumentParserToolInfo/ToolInfo.swift @@ -218,7 +218,23 @@ public struct ArgumentInfoV0: Codable, Hashable { self.kind = kind self.shouldDisplay = shouldDisplay - self.sectionTitle = sectionTitle + + // The section title helps categorize arguments + // for better organization in documentation. + + // The switch statement checks the kind of argument + // and assigns a default section title related to the argument type + // if the provided one is nil. + switch kind { + case .positional: + self.sectionTitle = sectionTitle ?? "Arguments" + + case .option: + self.sectionTitle = sectionTitle ?? "Optionals" + + case .flag: + self.sectionTitle = sectionTitle ?? "Flags" + } self.isOptional = isOptional self.isRepeating = isRepeating diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 966fd9cdd..af79af3df 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -6,22 +6,28 @@ color --fav= [--second=] [--help] ``` -**--fav=\:** +## Flags + +**`--help`** + +*Show help information.* + + +## Optionals + +**`--fav=\`** *Your favorite color.* -**--second=\:** +**`--second=\`** *Your second favorite color.* This is optional. -**--help:** - -*Show help information.* - +## Subcommands ## color.help @@ -31,9 +37,6 @@ Show subcommand help information. color help [...] ``` -**subcommands:** - - - - +## Arguments +**`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 88b97b538..3936e668f 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -6,26 +6,34 @@ count-lines [] [--prefix=] [--verbose] [--help] ``` -**input-file:** - -*A file to count lines in. If omitted, counts the lines of stdin.* +## Arguments +**`input-file`** -**--prefix=\:** +*A file to count lines in. If omitted, counts the lines of stdin.* -*Only count lines with this prefix.* +## Flags -**--verbose:** +**`--verbose`** *Include extra information in the output.* -**--help:** +**`--help`** *Show help information.* +## Optionals + +**`--prefix=\`** + +*Only count lines with this prefix.* + + +## Subcommands + ## count-lines.help Show subcommand help information. @@ -34,9 +42,6 @@ Show subcommand help information. count-lines help [...] ``` -**subcommands:** - - - - +## Arguments +**`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index adcaac132..5ea64d072 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -8,16 +8,20 @@ A utility for performing maths. math [--version] [--help] ``` -**--version:** +## Flags + +**`--version`** *Show the version.* -**--help:** +**`--help`** *Show help information.* +## Subcommands + ## math.add Print the sum of the values. @@ -26,29 +30,28 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -**--hex-output:** - -*Use hexadecimal notation for the result.* - +## Arguments -**values:** +**`values`** *A group of integers to operate on.* -**--version:** +## Flags -*Show the version.* +**`--hex-output`** +*Use hexadecimal notation for the result.* -**--help:** -*Show help information.* +**`--version`** +*Show the version.* +**`--help`** -## math.multiply +*Show help information.*## math.multiply Print the product of the values. @@ -56,29 +59,28 @@ Print the product of the values. math multiply [--hex-output] [...] [--version] [--help] ``` -**--hex-output:** - -*Use hexadecimal notation for the result.* +## Arguments - -**values:** +**`values`** *A group of integers to operate on.* -**--version:** +## Flags -*Show the version.* +**`--hex-output`** +*Use hexadecimal notation for the result.* -**--help:** -*Show help information.* +**`--version`** +*Show the version.* +**`--help`** -## math.stats +*Show help information.*## math.stats Calculate descriptive statistics. @@ -86,16 +88,20 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -**--version:** +## Flags + +**`--version`** *Show the version.* -**--help:** +**`--help`** *Show help information.* +## Subcommands + ### math.stats.average Print the average of the values. @@ -104,29 +110,30 @@ Print the average of the values. math stats average [--kind=] [...] [--version] [--help] ``` -**--kind=\:** - -*The kind of average to provide.* +## Arguments - -**values:** +**`values`** *A group of floating-point values to operate on.* -**--version:** +## Flags + +**`--version`** *Show the version.* -**--help:** +**`--help`** *Show help information.* +## Optionals +**`--kind=\`** -### math.stats.stdev +*The kind of average to provide.*### math.stats.stdev Print the standard deviation of the values. @@ -134,24 +141,23 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -**values:** +## Arguments -*A group of floating-point values to operate on.* - - -**--version:** +**`values`** -*Show the version.* +*A group of floating-point values to operate on.* -**--help:** +## Flags -*Show help information.* +**`--version`** +*Show the version.* +**`--help`** -### math.stats.quantiles +*Show help information.*### math.stats.quantiles Print the quantiles of the values (TBD). @@ -159,44 +165,43 @@ Print the quantiles of the values (TBD). math stats quantiles [] [] [...] [--file=] [--directory=] [--shell=] [--custom=] [--version] [--help] ``` -**one-of-four:** - - -**custom-arg:** - +## Arguments -**values:** +**`one-of-four`** -*A group of floating-point values to operate on.* +**`custom-arg`** -**--file=\:** +**`values`** -**--directory=\:** +*A group of floating-point values to operate on.* -**--shell=\:** +## Flags +**`--version`** -**--custom=\:** +*Show the version.* -**--version:** +**`--help`** -*Show the version.* +*Show help information.* -**--help:** +## Optionals -*Show help information.* +**`--file=\`** +**`--directory=\`** +**`--shell=\`** -## math.help +**`--custom=\`**## math.help Show subcommand help information. @@ -204,9 +209,6 @@ Show subcommand help information. math help [...] ``` -**subcommands:** - - - - +## Arguments +**`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 8d0714b48..ca3f01399 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -6,26 +6,34 @@ repeat [--count=] [--include-counter] [--help] ``` -**--count=\:** +## Arguments + +**`phrase`** + +*The phrase to repeat.* -*The number of times to repeat 'phrase'.* +## Flags -**--include-counter:** +**`--include-counter`** *Include a counter with each repetition.* -**phrase:** +**`--help`** -*The phrase to repeat.* +*Show help information.* -**--help:** +## Optionals -*Show help information.* +**`--count=\`** + +*The number of times to repeat 'phrase'.* +## Subcommands + ## repeat.help Show subcommand help information. @@ -34,9 +42,6 @@ Show subcommand help information. repeat help [...] ``` -**subcommands:** - - - - +## Arguments +**`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index d84e3e2b0..b53f228a1 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -6,32 +6,38 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -**--times=\:** +## Flags -*Rolls the dice times.* +**`--verbose`** +*Show all roll results.* -**--sides=\:** -*Rolls an -sided dice.* +**`--help`** -Use this option to override the default value of a six-sided die. +*Show help information.* -**--seed=\:** +## Optionals -*A seed to use for repeatable random generation.* +**`--times=\`** +*Rolls the dice times.* -**--verbose:** -*Show all roll results.* +**`--sides=\`** +*Rolls an -sided dice.* -**--help:** +Use this option to override the default value of a six-sided die. + + +**`--seed=\`** + +*A seed to use for repeatable random generation.* -*Show help information.* +## Subcommands ## roll.help @@ -41,9 +47,6 @@ Show subcommand help information. roll help [...] ``` -**subcommands:** - - - - +## Arguments +**`subcommands`** diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json index 7e180a263..efd1d7126 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json @@ -29,6 +29,7 @@ "kind" : "long", "name" : "enumerated-option" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "enumerated-option" }, @@ -61,6 +62,7 @@ "kind" : "long", "name" : "enumerated-option-with-default-value" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "enumerated-option-with-default-value" }, @@ -78,6 +80,7 @@ "kind" : "long", "name" : "no-help-option" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "no-help-option" }, @@ -96,6 +99,7 @@ "kind" : "long", "name" : "int-option" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "int-option" }, @@ -115,6 +119,7 @@ "kind" : "long", "name" : "int-option-with-default-value" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "int-option-with-default-value" }, @@ -122,6 +127,7 @@ "isOptional" : false, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg" }, @@ -130,6 +136,7 @@ "isOptional" : false, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg-with-help" }, @@ -139,6 +146,7 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg-with-default-value" }, @@ -161,6 +169,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -175,6 +184,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -200,6 +210,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json index 1fe07a4e9..f92d5fcd5 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json @@ -56,6 +56,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -70,6 +71,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -95,6 +97,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json index 2e115c010..eba5a09f3 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json @@ -35,6 +35,7 @@ "kind" : "long", "name" : "color" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "color" }, @@ -73,6 +74,7 @@ "kind" : "long", "name" : "default-color" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "default-color" }, @@ -110,6 +112,7 @@ "kind" : "long", "name" : "opt" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "opt" }, @@ -147,6 +150,7 @@ "kind" : "long", "name" : "extra" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "extra" }, @@ -165,6 +169,7 @@ "kind" : "long", "name" : "discussion" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "discussion" }, @@ -187,6 +192,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -201,6 +207,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -226,6 +233,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json index 099f7109d..3947d6a3e 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json @@ -21,6 +21,7 @@ "kind" : "long", "name" : "hex-output" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -29,6 +30,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -47,6 +49,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -69,6 +72,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -83,6 +87,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -108,6 +113,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json index af618a847..cc480a939 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json @@ -17,6 +17,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -39,6 +40,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -68,6 +70,7 @@ "kind" : "long", "name" : "hex-output" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -76,6 +79,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -94,6 +98,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -116,6 +121,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -148,6 +154,7 @@ "kind" : "long", "name" : "hex-output" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -156,6 +163,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -174,6 +182,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -196,6 +205,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -224,6 +234,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -246,6 +257,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -286,6 +298,7 @@ "kind" : "long", "name" : "kind" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "kind" }, @@ -294,6 +307,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -312,6 +326,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -334,6 +349,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -353,6 +369,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -371,6 +388,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -393,6 +411,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -421,6 +440,7 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "one-of-four" }, @@ -433,6 +453,7 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "custom-arg" }, @@ -441,6 +462,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -458,6 +480,7 @@ "kind" : "long", "name" : "test-success-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -475,6 +498,7 @@ "kind" : "long", "name" : "test-failure-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -492,6 +516,7 @@ "kind" : "long", "name" : "test-validation-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -509,6 +534,7 @@ "kind" : "long", "name" : "test-custom-exit-code" }, + "sectionTitle" : "Optionals", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, @@ -534,6 +560,7 @@ "kind" : "long", "name" : "file" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "file" }, @@ -556,6 +583,7 @@ "kind" : "long", "name" : "directory" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "directory" }, @@ -578,6 +606,7 @@ "kind" : "long", "name" : "shell" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "shell" }, @@ -600,6 +629,7 @@ "kind" : "long", "name" : "custom" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "custom" }, @@ -618,6 +648,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -640,6 +671,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -663,6 +695,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -688,6 +721,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json index dd1f96723..36c9cf49d 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json @@ -21,6 +21,7 @@ "kind" : "long", "name" : "hex-output" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -29,6 +30,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -47,6 +49,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -69,6 +72,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -83,6 +87,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -108,6 +113,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json index edc0b3153..f9e8a36fb 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json @@ -17,6 +17,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -39,6 +40,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -79,6 +81,7 @@ "kind" : "long", "name" : "kind" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "kind" }, @@ -87,6 +90,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -105,6 +109,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -127,6 +132,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -146,6 +152,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -164,6 +171,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -186,6 +194,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -214,6 +223,7 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "one-of-four" }, @@ -226,6 +236,7 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "custom-arg" }, @@ -234,6 +245,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -251,6 +263,7 @@ "kind" : "long", "name" : "test-success-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -268,6 +281,7 @@ "kind" : "long", "name" : "test-failure-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -285,6 +299,7 @@ "kind" : "long", "name" : "test-validation-exit-code" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -302,6 +317,7 @@ "kind" : "long", "name" : "test-custom-exit-code" }, + "sectionTitle" : "Optionals", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, @@ -327,6 +343,7 @@ "kind" : "long", "name" : "file" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "file" }, @@ -349,6 +366,7 @@ "kind" : "long", "name" : "directory" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "directory" }, @@ -371,6 +389,7 @@ "kind" : "long", "name" : "shell" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "shell" }, @@ -393,6 +412,7 @@ "kind" : "long", "name" : "custom" }, + "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "custom" }, @@ -411,6 +431,7 @@ "kind" : "long", "name" : "version" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -433,6 +454,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -451,6 +473,7 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", + "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -476,6 +499,7 @@ "kind" : "long", "name" : "help" }, + "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 05e187061..d175b3ebc 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -59,26 +59,71 @@ extension CommandInfoV0 { } if let args = self.arguments { - for arg in args { - guard arg.shouldDisplay else { - continue + // Group arguments by sectionTitle + // This is done to organize the arguments into categories (e.g., optionals, flags) + let groupedArgs = Dictionary( + grouping: args.filter { + $0.shouldDisplay } - - result += "**\(arg.identity()):**\n\n" - if let abstract = arg.abstract { - result += "*\(abstract)*\n\n" - } - if let discussion = arg.discussion { - result += discussion + "\n\n" + ) { $0.sectionTitle ?? "General" } + + // Iterate through the grouped arguments, sorted by section title + // Sorting ensures that the sections appear in a clear, predictable order in the final documentation. + // The sections are listed alphabetically based on their title, enhancing readability. + for (section, arguments) in groupedArgs.sorted(by: { $0.key < $1.key }) { + // Add section title as a Markdown header to the result + // Adding section titles as Markdown headers helps separate sections in the documentation, + // making it easier for users to navigate and understand the structure of the arguments. + result += "## \(section)\n\n" + + // Iterate through each argument in the section + // Iterating through each argument allows us to add details for each argument under its respective section. + for arg in arguments { + // Add the argument identity in bold Markdown format + // The argument identity is emphasized in bold to make it stand out in the documentation. + result += "**`\(arg.identity())`**\n\n" + + // If the argument has an abstract, add it in italic Markdown format + // Including the abstract provides a brief description of the argument's purpose. + // The italic formatting helps to distinguish the abstract from other parts of the documentation. + if let abstract = arg.abstract { + result += "*\(abstract)*\n\n" + } + + // If the argument has a discussion, add it directly + // If a discussion is available, it is added to provide further explanation on how the argument works. + // This additional context is helpful for users to understand the full usage of the argument. + if let discussion = arg.discussion { + result += discussion + "\n\n" + } + + // Add an empty line for separation between arguments + // The empty line improves the visual structure of the documentation, + // making it easier to read and separating each argument for clarity. + result += "\n" } - result += "\n" } } - for subcommand in self.subcommands ?? [] { - result += subcommand.toMarkdown(path + [self.commandName]) + "\n\n" + if let subcommands = self.subcommands, !subcommands.isEmpty { + // Add a separate section for subcommands. + // Subcommands are treated differently from regular arguments, so they deserve their own section in the documentation. + // This helps to visually distinguish subcommands from regular arguments, enhancing readability. + result += "## Subcommands\n\n" + + // Iterate through each subcommand and convert it to Markdown format + // Each subcommand is processed and added to the documentation under the "Subcommands" section. + // This ensures that users can easily identify and understand the subcommands available for the command. + for subcommand in subcommands { + result += subcommand.toMarkdown(path + [self.commandName]) + } } + // Trim any unnecessary trailing newline that could have been added inadvertently + // By trimming, we prevent extra lines at the end of the generated document + // which is important for snapshot comparison. + result = result.trimmingCharacters(in: .newlines) + return result } From 806544c7caaa1e69269816829f64026a04fc908c Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Fri, 4 Apr 2025 02:48:57 +0330 Subject: [PATCH 2/5] fix: handle the assignment of the default sectionTitle value in the generate-docc command instead of in toolinfo --- Sources/ArgumentParserToolInfo/ToolInfo.swift | 18 +---- .../Snapshots/testColorDoccReference().md | 4 +- .../testCountLinesDoccReference().md | 4 +- .../Snapshots/testMathDoccReference().md | 72 ++++++++----------- .../Snapshots/testRepeatDoccReference().md | 4 +- .../Snapshots/testRollDoccReference().md | 4 +- .../Snapshots/testADumpHelp().json | 11 --- .../Snapshots/testBDumpHelp().json | 3 - .../Snapshots/testCDumpHelp().json | 8 --- .../Snapshots/testMathAddDumpHelp().json | 6 -- .../Snapshots/testMathDumpHelp().json | 34 --------- .../Snapshots/testMathMultiplyDumpHelp().json | 6 -- .../Snapshots/testMathStatsDumpHelp().json | 24 ------- .../GenerateDoccReference.swift | 44 +++++++++++- 14 files changed, 81 insertions(+), 161 deletions(-) diff --git a/Sources/ArgumentParserToolInfo/ToolInfo.swift b/Sources/ArgumentParserToolInfo/ToolInfo.swift index 0b3f23190..926bb5156 100644 --- a/Sources/ArgumentParserToolInfo/ToolInfo.swift +++ b/Sources/ArgumentParserToolInfo/ToolInfo.swift @@ -218,23 +218,7 @@ public struct ArgumentInfoV0: Codable, Hashable { self.kind = kind self.shouldDisplay = shouldDisplay - - // The section title helps categorize arguments - // for better organization in documentation. - - // The switch statement checks the kind of argument - // and assigns a default section title related to the argument type - // if the provided one is nil. - switch kind { - case .positional: - self.sectionTitle = sectionTitle ?? "Arguments" - - case .option: - self.sectionTitle = sectionTitle ?? "Optionals" - - case .flag: - self.sectionTitle = sectionTitle ?? "Flags" - } + self.sectionTitle = sectionTitle self.isOptional = isOptional self.isRepeating = isRepeating diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index af79af3df..eb6608ea5 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -13,7 +13,7 @@ color --fav= [--second=] [--help] *Show help information.* -## Optionals +## Options **`--fav=\`** @@ -37,6 +37,6 @@ Show subcommand help information. color help [...] ``` -## Arguments +## General **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 3936e668f..c37f2a118 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -25,7 +25,7 @@ count-lines [] [--prefix=] [--verbose] [--help] *Show help information.* -## Optionals +## Options **`--prefix=\`** @@ -42,6 +42,6 @@ Show subcommand help information. count-lines help [...] ``` -## Arguments +## General **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 5ea64d072..2bd2803c8 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -30,18 +30,16 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -## Arguments +## General -**`values`** - -*A group of integers to operate on.* +**`--hex-output`** +*Use hexadecimal notation for the result.* -## Flags -**`--hex-output`** +**`values`** -*Use hexadecimal notation for the result.* +*A group of integers to operate on.* **`--version`** @@ -59,18 +57,16 @@ Print the product of the values. math multiply [--hex-output] [...] [--version] [--help] ``` -## Arguments +## General -**`values`** - -*A group of integers to operate on.* +**`--hex-output`** +*Use hexadecimal notation for the result.* -## Flags -**`--hex-output`** +**`values`** -*Use hexadecimal notation for the result.* +*A group of integers to operate on.* **`--version`** @@ -88,7 +84,7 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -## Flags +## General **`--version`** @@ -110,15 +106,18 @@ Print the average of the values. math stats average [--kind=] [...] [--version] [--help] ``` -## Arguments +## General + +**`--kind=\`** + +*The kind of average to provide.* + **`values`** *A group of floating-point values to operate on.* -## Flags - **`--version`** *Show the version.* @@ -126,14 +125,7 @@ math stats average [--kind=] [...] [--version] [--help] **`--help`** -*Show help information.* - - -## Optionals - -**`--kind=\`** - -*The kind of average to provide.*### math.stats.stdev +*Show help information.*### math.stats.stdev Print the standard deviation of the values. @@ -141,15 +133,13 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -## Arguments +## General **`values`** *A group of floating-point values to operate on.* -## Flags - **`--version`** *Show the version.* @@ -165,7 +155,7 @@ Print the quantiles of the values (TBD). math stats quantiles [] [] [...] [--file=] [--directory=] [--shell=] [--custom=] [--version] [--help] ``` -## Arguments +## General **`one-of-four`** @@ -178,30 +168,26 @@ math stats quantiles [] [] [...] [--file=`** -**`--help`** +**`--directory=\`** -*Show help information.* +**`--shell=\`** -## Optionals -**`--file=\`** +**`--custom=\`** -**`--directory=\`** +**`--version`** +*Show the version.* -**`--shell=\`** +**`--help`** -**`--custom=\`**## math.help +*Show help information.*## math.help Show subcommand help information. @@ -209,6 +195,6 @@ Show subcommand help information. math help [...] ``` -## Arguments +## General **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index ca3f01399..d32a4c739 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -25,7 +25,7 @@ repeat [--count=] [--include-counter] [--help] *Show help information.* -## Optionals +## Options **`--count=\`** @@ -42,6 +42,6 @@ Show subcommand help information. repeat help [...] ``` -## Arguments +## General **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index b53f228a1..28430fa0b 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -18,7 +18,7 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] *Show help information.* -## Optionals +## Options **`--times=\`** @@ -47,6 +47,6 @@ Show subcommand help information. roll help [...] ``` -## Arguments +## General **`subcommands`** diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json index efd1d7126..7e180a263 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testADumpHelp().json @@ -29,7 +29,6 @@ "kind" : "long", "name" : "enumerated-option" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "enumerated-option" }, @@ -62,7 +61,6 @@ "kind" : "long", "name" : "enumerated-option-with-default-value" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "enumerated-option-with-default-value" }, @@ -80,7 +78,6 @@ "kind" : "long", "name" : "no-help-option" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "no-help-option" }, @@ -99,7 +96,6 @@ "kind" : "long", "name" : "int-option" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "int-option" }, @@ -119,7 +115,6 @@ "kind" : "long", "name" : "int-option-with-default-value" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "int-option-with-default-value" }, @@ -127,7 +122,6 @@ "isOptional" : false, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg" }, @@ -136,7 +130,6 @@ "isOptional" : false, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg-with-help" }, @@ -146,7 +139,6 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "arg-with-default-value" }, @@ -169,7 +161,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -184,7 +175,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -210,7 +200,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json index f92d5fcd5..1fe07a4e9 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testBDumpHelp().json @@ -56,7 +56,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -71,7 +70,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -97,7 +95,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json index eba5a09f3..2e115c010 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testCDumpHelp().json @@ -35,7 +35,6 @@ "kind" : "long", "name" : "color" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "color" }, @@ -74,7 +73,6 @@ "kind" : "long", "name" : "default-color" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "default-color" }, @@ -112,7 +110,6 @@ "kind" : "long", "name" : "opt" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "opt" }, @@ -150,7 +147,6 @@ "kind" : "long", "name" : "extra" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "extra" }, @@ -169,7 +165,6 @@ "kind" : "long", "name" : "discussion" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "discussion" }, @@ -192,7 +187,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -207,7 +201,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -233,7 +226,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json index 3947d6a3e..099f7109d 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathAddDumpHelp().json @@ -21,7 +21,6 @@ "kind" : "long", "name" : "hex-output" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -30,7 +29,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -49,7 +47,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -72,7 +69,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -87,7 +83,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -113,7 +108,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json index cc480a939..af618a847 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json @@ -17,7 +17,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -40,7 +39,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -70,7 +68,6 @@ "kind" : "long", "name" : "hex-output" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -79,7 +76,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -98,7 +94,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -121,7 +116,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -154,7 +148,6 @@ "kind" : "long", "name" : "hex-output" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -163,7 +156,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -182,7 +174,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -205,7 +196,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -234,7 +224,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -257,7 +246,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -298,7 +286,6 @@ "kind" : "long", "name" : "kind" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "kind" }, @@ -307,7 +294,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -326,7 +312,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -349,7 +334,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -369,7 +353,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -388,7 +371,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -411,7 +393,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -440,7 +421,6 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "one-of-four" }, @@ -453,7 +433,6 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "custom-arg" }, @@ -462,7 +441,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -480,7 +458,6 @@ "kind" : "long", "name" : "test-success-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -498,7 +475,6 @@ "kind" : "long", "name" : "test-failure-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -516,7 +492,6 @@ "kind" : "long", "name" : "test-validation-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -534,7 +509,6 @@ "kind" : "long", "name" : "test-custom-exit-code" }, - "sectionTitle" : "Optionals", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, @@ -560,7 +534,6 @@ "kind" : "long", "name" : "file" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "file" }, @@ -583,7 +556,6 @@ "kind" : "long", "name" : "directory" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "directory" }, @@ -606,7 +578,6 @@ "kind" : "long", "name" : "shell" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "shell" }, @@ -629,7 +600,6 @@ "kind" : "long", "name" : "custom" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "custom" }, @@ -648,7 +618,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -671,7 +640,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -695,7 +663,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -721,7 +688,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json index 36c9cf49d..dd1f96723 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathMultiplyDumpHelp().json @@ -21,7 +21,6 @@ "kind" : "long", "name" : "hex-output" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "hex-output" }, @@ -30,7 +29,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -49,7 +47,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -72,7 +69,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -87,7 +83,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -113,7 +108,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json index f9e8a36fb..edc0b3153 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json @@ -17,7 +17,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -40,7 +39,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -81,7 +79,6 @@ "kind" : "long", "name" : "kind" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "kind" }, @@ -90,7 +87,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -109,7 +105,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -132,7 +127,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -152,7 +146,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -171,7 +164,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -194,7 +186,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -223,7 +214,6 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "one-of-four" }, @@ -236,7 +226,6 @@ "isOptional" : true, "isRepeating" : false, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "custom-arg" }, @@ -245,7 +234,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "values" }, @@ -263,7 +251,6 @@ "kind" : "long", "name" : "test-success-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -281,7 +268,6 @@ "kind" : "long", "name" : "test-failure-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -299,7 +285,6 @@ "kind" : "long", "name" : "test-validation-exit-code" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -317,7 +302,6 @@ "kind" : "long", "name" : "test-custom-exit-code" }, - "sectionTitle" : "Optionals", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, @@ -343,7 +327,6 @@ "kind" : "long", "name" : "file" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "file" }, @@ -366,7 +349,6 @@ "kind" : "long", "name" : "directory" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "directory" }, @@ -389,7 +371,6 @@ "kind" : "long", "name" : "shell" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "shell" }, @@ -412,7 +393,6 @@ "kind" : "long", "name" : "custom" }, - "sectionTitle" : "Optionals", "shouldDisplay" : true, "valueName" : "custom" }, @@ -431,7 +411,6 @@ "kind" : "long", "name" : "version" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "version" }, @@ -454,7 +433,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : true, "valueName" : "help" } @@ -473,7 +451,6 @@ "isOptional" : true, "isRepeating" : true, "kind" : "positional", - "sectionTitle" : "Arguments", "shouldDisplay" : true, "valueName" : "subcommands" }, @@ -499,7 +476,6 @@ "kind" : "long", "name" : "help" }, - "sectionTitle" : "Flags", "shouldDisplay" : false, "valueName" : "help" } diff --git a/Tools/generate-docc-reference/GenerateDoccReference.swift b/Tools/generate-docc-reference/GenerateDoccReference.swift index c5f1c6a0e..77a9b2323 100644 --- a/Tools/generate-docc-reference/GenerateDoccReference.swift +++ b/Tools/generate-docc-reference/GenerateDoccReference.swift @@ -18,6 +18,7 @@ enum GenerateDoccReferenceError: Error { case unableToParseToolOutput(error: Error) case unsupportedDumpHelpVersion(expected: Int, found: Int) case failedToGenerateDoccReference(error: Error) + case argumentAssignmentFailed(description: String) } extension GenerateDoccReferenceError: CustomStringConvertible { @@ -32,6 +33,8 @@ extension GenerateDoccReferenceError: CustomStringConvertible { "Unsupported dump help version, expected '\(expected)' but found: '\(found)'" case .failedToGenerateDoccReference(let error): return "Failed to generated docc reference: \(error)" + case .argumentAssignmentFailed(let description): + return "Argument assignment failed: \(description)" } } } @@ -92,13 +95,37 @@ struct GenerateDoccReference: ParsableCommand { throw GenerateDoccReferenceError.unableToParseToolOutput(error: error) } - let toolInfo: ToolInfoV0 + var toolInfo: ToolInfoV0 + do { toolInfo = try JSONDecoder().decode(ToolInfoV0.self, from: data) } catch { throw GenerateDoccReferenceError.unableToParseToolOutput(error: error) } + do { + // Ensure each argument has a properly categorized section title. + // This improves documentation clarity and makes the generated output easier to navigate. + var modifiedArguments = toolInfo.command.arguments ?? [] + + // Assign a section title to the argument to ensure it's correctly classified + // (e.g., positional arguments, options, or flags). This enhances the structure + // of the generated docc reference. + modifiedArguments = try modifiedArguments.map { argument in + var modifiedArgument = argument + modifiedArgument.sectionTitle = try assignSectionTitle(to: argument) + + return modifiedArgument + } + + toolInfo.command.arguments = modifiedArguments + } catch { + throw GenerateDoccReferenceError.argumentAssignmentFailed( + description: + "Failed to assign section titles to arguments: \(error.localizedDescription)" + ) + } + do { if self.outputDirectory == "-" { try self.generatePages(from: toolInfo.command, savingTo: nil) @@ -126,4 +153,19 @@ struct GenerateDoccReference: ParsableCommand { print(page) } } + + func assignSectionTitle(to argument: ArgumentInfoV0) throws -> String { + if let sectionTitle = argument.sectionTitle { + return sectionTitle + } else { + switch argument.kind { + case .positional: + return "Arguments" + case .option: + return "Options" + case .flag: + return "Flags" + } + } + } } From 49f9f697ca04c2d671830546b770d7f3459ac681 Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Sat, 12 Apr 2025 17:33:41 +0330 Subject: [PATCH 3/5] fix: handling section titles in the GenerateDocc extension --- .../Snapshots/testColorDoccReference().md | 4 +- .../testCountLinesDoccReference().md | 4 +- .../Snapshots/testMathDoccReference().md | 92 +++++++++++-------- .../Snapshots/testRepeatDoccReference().md | 4 +- .../Snapshots/testRollDoccReference().md | 4 +- .../Extensions/ArgumentParser+Markdown.swift | 33 ++++--- .../GenerateDoccReference.swift | 46 +--------- 7 files changed, 82 insertions(+), 105 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index eb6608ea5..90fce9bde 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -27,8 +27,6 @@ color --fav= [--second=] [--help] This is optional. -## Subcommands - ## color.help Show subcommand help information. @@ -37,6 +35,6 @@ Show subcommand help information. color help [...] ``` -## General +## Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index c37f2a118..df5c460a0 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -32,8 +32,6 @@ count-lines [] [--prefix=] [--verbose] [--help] *Only count lines with this prefix.* -## Subcommands - ## count-lines.help Show subcommand help information. @@ -42,6 +40,6 @@ Show subcommand help information. count-lines help [...] ``` -## General +## Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 2bd2803c8..dd19fe656 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -20,8 +20,6 @@ math [--version] [--help] *Show help information.* -## Subcommands - ## math.add Print the sum of the values. @@ -30,16 +28,18 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -## General +## Arguments -**`--hex-output`** +**`values`** -*Use hexadecimal notation for the result.* +*A group of integers to operate on.* -**`values`** +## Flags -*A group of integers to operate on.* +**`--hex-output`** + +*Use hexadecimal notation for the result.* **`--version`** @@ -49,7 +49,9 @@ math add [--hex-output] [...] [--version] [--help] **`--help`** -*Show help information.*## math.multiply +*Show help information.* + +## math.multiply Print the product of the values. @@ -57,16 +59,18 @@ Print the product of the values. math multiply [--hex-output] [...] [--version] [--help] ``` -## General +## Arguments -**`--hex-output`** +**`values`** -*Use hexadecimal notation for the result.* +*A group of integers to operate on.* -**`values`** +## Flags -*A group of integers to operate on.* +**`--hex-output`** + +*Use hexadecimal notation for the result.* **`--version`** @@ -76,7 +80,9 @@ math multiply [--hex-output] [...] [--version] [--help] **`--help`** -*Show help information.*## math.stats +*Show help information.* + +## math.stats Calculate descriptive statistics. @@ -84,7 +90,7 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -## General +## Flags **`--version`** @@ -96,8 +102,6 @@ math stats [--version] [--help] *Show help information.* -## Subcommands - ### math.stats.average Print the average of the values. @@ -106,18 +110,15 @@ Print the average of the values. math stats average [--kind=] [...] [--version] [--help] ``` -## General - -**`--kind=\`** - -*The kind of average to provide.* - +## Arguments **`values`** *A group of floating-point values to operate on.* +## Flags + **`--version`** *Show the version.* @@ -125,7 +126,16 @@ math stats average [--kind=] [...] [--version] [--help] **`--help`** -*Show help information.*### math.stats.stdev +*Show help information.* + + +## Options + +**`--kind=\`** + +*The kind of average to provide.* + +### math.stats.stdev Print the standard deviation of the values. @@ -133,13 +143,15 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -## General +## Arguments **`values`** *A group of floating-point values to operate on.* +## Flags + **`--version`** *Show the version.* @@ -147,7 +159,9 @@ math stats stdev [...] [--version] [--help] **`--help`** -*Show help information.*### math.stats.quantiles +*Show help information.* + +### math.stats.quantiles Print the quantiles of the values (TBD). @@ -155,7 +169,7 @@ Print the quantiles of the values (TBD). math stats quantiles [] [] [...] [--file=] [--directory=] [--shell=] [--custom=] [--version] [--help] ``` -## General +## Arguments **`one-of-four`** @@ -168,26 +182,32 @@ math stats quantiles [] [] [...] [--file=`** +## Flags + +**`--version`** + +*Show the version.* -**`--directory=\`** +**`--help`** +*Show help information.* -**`--shell=\`** +## Options -**`--custom=\`** +**`--file=\`** -**`--version`** +**`--directory=\`** -*Show the version.* +**`--shell=\`** -**`--help`** -*Show help information.*## math.help +**`--custom=\`** + +## math.help Show subcommand help information. @@ -195,6 +215,6 @@ Show subcommand help information. math help [...] ``` -## General +## Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index d32a4c739..568a18580 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -32,8 +32,6 @@ repeat [--count=] [--include-counter] [--help] *The number of times to repeat 'phrase'.* -## Subcommands - ## repeat.help Show subcommand help information. @@ -42,6 +40,6 @@ Show subcommand help information. repeat help [...] ``` -## General +## Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index 28430fa0b..ae35f35f2 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -37,8 +37,6 @@ Use this option to override the default value of a six-sided die. *A seed to use for repeatable random generation.* -## Subcommands - ## roll.help Show subcommand help information. @@ -47,6 +45,6 @@ Show subcommand help information. roll help [...] ``` -## General +## Arguments **`subcommands`** diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index d175b3ebc..c61a9ca83 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -65,7 +65,7 @@ extension CommandInfoV0 { grouping: args.filter { $0.shouldDisplay } - ) { $0.sectionTitle ?? "General" } + ) { self.assignSectionTitle(to: $0) } // Iterate through the grouped arguments, sorted by section title // Sorting ensures that the sections appear in a clear, predictable order in the final documentation. @@ -105,18 +105,8 @@ extension CommandInfoV0 { } } - if let subcommands = self.subcommands, !subcommands.isEmpty { - // Add a separate section for subcommands. - // Subcommands are treated differently from regular arguments, so they deserve their own section in the documentation. - // This helps to visually distinguish subcommands from regular arguments, enhancing readability. - result += "## Subcommands\n\n" - - // Iterate through each subcommand and convert it to Markdown format - // Each subcommand is processed and added to the documentation under the "Subcommands" section. - // This ensures that users can easily identify and understand the subcommands available for the command. - for subcommand in subcommands { - result += subcommand.toMarkdown(path + [self.commandName]) - } + for subcommand in self.subcommands ?? [] { + result += subcommand.toMarkdown(path + [self.commandName]) + "\n\n" } // Trim any unnecessary trailing newline that could have been added inadvertently @@ -134,8 +124,25 @@ extension CommandInfoV0 { return args.map { $0.usage() }.joined(separator: " ") } + + // Assign a default section title based on the arguments types + func assignSectionTitle(to argument: ArgumentInfoV0) -> String { + if let sectionTitle = argument.sectionTitle { + return sectionTitle + } else { + switch argument.kind { + case .positional: + return "Arguments" + case .option: + return "Options" + case .flag: + return "Flags" + } + } + } } + extension ArgumentInfoV0 { public func usage() -> String { guard self.shouldDisplay else { diff --git a/Tools/generate-docc-reference/GenerateDoccReference.swift b/Tools/generate-docc-reference/GenerateDoccReference.swift index 77a9b2323..23be48c2f 100644 --- a/Tools/generate-docc-reference/GenerateDoccReference.swift +++ b/Tools/generate-docc-reference/GenerateDoccReference.swift @@ -18,7 +18,6 @@ enum GenerateDoccReferenceError: Error { case unableToParseToolOutput(error: Error) case unsupportedDumpHelpVersion(expected: Int, found: Int) case failedToGenerateDoccReference(error: Error) - case argumentAssignmentFailed(description: String) } extension GenerateDoccReferenceError: CustomStringConvertible { @@ -29,12 +28,9 @@ extension GenerateDoccReferenceError: CustomStringConvertible { case .unableToParseToolOutput(let error): return "Failed to parse tool output: \(error)" case .unsupportedDumpHelpVersion(let expected, let found): - return - "Unsupported dump help version, expected '\(expected)' but found: '\(found)'" + return "Unsupported dump help version, expected '\(expected)' but found: '\(found)'" case .failedToGenerateDoccReference(let error): return "Failed to generated docc reference: \(error)" - case .argumentAssignmentFailed(let description): - return "Argument assignment failed: \(description)" } } } @@ -102,30 +98,7 @@ struct GenerateDoccReference: ParsableCommand { } catch { throw GenerateDoccReferenceError.unableToParseToolOutput(error: error) } - - do { - // Ensure each argument has a properly categorized section title. - // This improves documentation clarity and makes the generated output easier to navigate. - var modifiedArguments = toolInfo.command.arguments ?? [] - - // Assign a section title to the argument to ensure it's correctly classified - // (e.g., positional arguments, options, or flags). This enhances the structure - // of the generated docc reference. - modifiedArguments = try modifiedArguments.map { argument in - var modifiedArgument = argument - modifiedArgument.sectionTitle = try assignSectionTitle(to: argument) - - return modifiedArgument - } - - toolInfo.command.arguments = modifiedArguments - } catch { - throw GenerateDoccReferenceError.argumentAssignmentFailed( - description: - "Failed to assign section titles to arguments: \(error.localizedDescription)" - ) - } - + do { if self.outputDirectory == "-" { try self.generatePages(from: toolInfo.command, savingTo: nil) @@ -153,19 +126,4 @@ struct GenerateDoccReference: ParsableCommand { print(page) } } - - func assignSectionTitle(to argument: ArgumentInfoV0) throws -> String { - if let sectionTitle = argument.sectionTitle { - return sectionTitle - } else { - switch argument.kind { - case .positional: - return "Arguments" - case .option: - return "Options" - case .flag: - return "Flags" - } - } - } } From fa6f077233fc34a4240edb3d06e89f7b27792c49 Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Sun, 20 Apr 2025 14:01:49 +0330 Subject: [PATCH 4/5] refactor: update markdown headers to align with DocC formatting --- .../Snapshots/testColorDoccReference().md | 6 ++-- .../testCountLinesDoccReference().md | 8 ++--- .../Snapshots/testMathDoccReference().md | 30 +++++++++---------- .../Snapshots/testRepeatDoccReference().md | 8 ++--- .../Snapshots/testRollDoccReference().md | 6 ++-- .../Extensions/ArgumentParser+Markdown.swift | 2 +- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 90fce9bde..d087a6ad8 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -6,14 +6,14 @@ color --fav= [--second=] [--help] ``` -## Flags +### Flags **`--help`** *Show help information.* -## Options +### Options **`--fav=\`** @@ -35,6 +35,6 @@ Show subcommand help information. color help [...] ``` -## Arguments +### Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index df5c460a0..29ca58c78 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -6,14 +6,14 @@ count-lines [] [--prefix=] [--verbose] [--help] ``` -## Arguments +### Arguments **`input-file`** *A file to count lines in. If omitted, counts the lines of stdin.* -## Flags +### Flags **`--verbose`** @@ -25,7 +25,7 @@ count-lines [] [--prefix=] [--verbose] [--help] *Show help information.* -## Options +### Options **`--prefix=\`** @@ -40,6 +40,6 @@ Show subcommand help information. count-lines help [...] ``` -## Arguments +### Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index dd19fe656..e28085f58 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -8,7 +8,7 @@ A utility for performing maths. math [--version] [--help] ``` -## Flags +### Flags **`--version`** @@ -28,14 +28,14 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -## Arguments +### Arguments **`values`** *A group of integers to operate on.* -## Flags +### Flags **`--hex-output`** @@ -59,14 +59,14 @@ Print the product of the values. math multiply [--hex-output] [...] [--version] [--help] ``` -## Arguments +### Arguments **`values`** *A group of integers to operate on.* -## Flags +### Flags **`--hex-output`** @@ -90,7 +90,7 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -## Flags +### Flags **`--version`** @@ -110,14 +110,14 @@ Print the average of the values. math stats average [--kind=] [...] [--version] [--help] ``` -## Arguments +### Arguments **`values`** *A group of floating-point values to operate on.* -## Flags +### Flags **`--version`** @@ -129,7 +129,7 @@ math stats average [--kind=] [...] [--version] [--help] *Show help information.* -## Options +### Options **`--kind=\`** @@ -143,14 +143,14 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -## Arguments +### Arguments **`values`** *A group of floating-point values to operate on.* -## Flags +### Flags **`--version`** @@ -169,7 +169,7 @@ Print the quantiles of the values (TBD). math stats quantiles [] [] [...] [--file=] [--directory=] [--shell=] [--custom=] [--version] [--help] ``` -## Arguments +### Arguments **`one-of-four`** @@ -182,7 +182,7 @@ math stats quantiles [] [] [...] [--file=] [] [...] [--file=`** @@ -215,6 +215,6 @@ Show subcommand help information. math help [...] ``` -## Arguments +### Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 568a18580..4db5dc3b1 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -6,14 +6,14 @@ repeat [--count=] [--include-counter] [--help] ``` -## Arguments +### Arguments **`phrase`** *The phrase to repeat.* -## Flags +### Flags **`--include-counter`** @@ -25,7 +25,7 @@ repeat [--count=] [--include-counter] [--help] *Show help information.* -## Options +### Options **`--count=\`** @@ -40,6 +40,6 @@ Show subcommand help information. repeat help [...] ``` -## Arguments +### Arguments **`subcommands`** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index ae35f35f2..eb0e15c7c 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -6,7 +6,7 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -## Flags +### Flags **`--verbose`** @@ -18,7 +18,7 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] *Show help information.* -## Options +### Options **`--times=\`** @@ -45,6 +45,6 @@ Show subcommand help information. roll help [...] ``` -## Arguments +### Arguments **`subcommands`** diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index c61a9ca83..9b9966906 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -74,7 +74,7 @@ extension CommandInfoV0 { // Add section title as a Markdown header to the result // Adding section titles as Markdown headers helps separate sections in the documentation, // making it easier for users to navigate and understand the structure of the arguments. - result += "## \(section)\n\n" + result += "### \(section)\n\n" // Iterate through each argument in the section // Iterating through each argument allows us to add details for each argument under its respective section. From 7659317bc5487aa4c6fc16fb83e9fec855622759 Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Tue, 1 Jul 2025 18:35:31 +0330 Subject: [PATCH 5/5] fix: update argument categorization logic to match ArgumentParser standard help output --- .../Snapshots/testColorDoccReference().md | 14 +++--- .../Snapshots/testColorMarkdownReference().md | 14 +++--- .../testCountLinesDoccReference().md | 16 +++--- .../testCountLinesMarkdownReference().md | 16 +++--- .../Snapshots/testMathDoccReference().md | 50 +++++++++---------- .../Snapshots/testMathMarkdownReference().md | 50 +++++++++---------- .../Snapshots/testRepeatDoccReference().md | 16 +++--- .../testRepeatMarkdownReference().md | 16 +++--- .../Snapshots/testRollDoccReference().md | 24 ++++----- .../Snapshots/testRollMarkdownReference().md | 24 ++++----- .../Extensions/ArgumentParser+Markdown.swift | 12 +++-- 11 files changed, 127 insertions(+), 125 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 590b25b43..3c93125da 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -6,13 +6,6 @@ color --fav= [--second=] [--help] ``` -### Flags - -- term **--help:** - -*Show help information.* - - ### Options - term **--fav=\:** @@ -27,6 +20,11 @@ color --fav= [--second=] [--help] This is optional. +- term **--help:** + +*Show help information.* + + ## color.help Show subcommand help information. @@ -38,3 +36,5 @@ color help [...] ### Arguments - term **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md index 4e08d6f31..e2e944b91 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -6,13 +6,6 @@ color --fav= [--second=] [--help] ``` -### Flags - -**--help:** - -*Show help information.* - - ### Options **--fav=\:** @@ -27,6 +20,11 @@ color --fav= [--second=] [--help] This is optional. +**--help:** + +*Show help information.* + + ## color.help Show subcommand help information. @@ -38,3 +36,5 @@ color help [...] ### Arguments **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 06ba14aa3..797b73c2d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -13,7 +13,12 @@ count-lines [] [--prefix=] [--verbose] [--help] *A file to count lines in. If omitted, counts the lines of stdin.* -### Flags +### Options + +- term **--prefix=\:** + +*Only count lines with this prefix.* + - term **--verbose:** @@ -25,13 +30,6 @@ count-lines [] [--prefix=] [--verbose] [--help] *Show help information.* -### Options - -- term **--prefix=\:** - -*Only count lines with this prefix.* - - ## count-lines.help Show subcommand help information. @@ -43,3 +41,5 @@ count-lines help [...] ### Arguments - term **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md index 20e2a382c..3146ee17d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -13,7 +13,12 @@ count-lines [] [--prefix=] [--verbose] [--help] *A file to count lines in. If omitted, counts the lines of stdin.* -### Flags +### Options + +**--prefix=\:** + +*Only count lines with this prefix.* + **--verbose:** @@ -25,13 +30,6 @@ count-lines [] [--prefix=] [--verbose] [--help] *Show help information.* -### Options - -**--prefix=\:** - -*Only count lines with this prefix.* - - ## count-lines.help Show subcommand help information. @@ -43,3 +41,5 @@ count-lines help [...] ### Arguments **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 49bf79c3a..2633dda61 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -8,7 +8,7 @@ A utility for performing maths. math [--version] [--help] ``` -### Flags +### Options - term **--version:** @@ -35,7 +35,7 @@ math add [--hex-output] [...] [--version] [--help] *A group of integers to operate on.* -### Flags +### Options - term **--hex-output:** @@ -66,7 +66,7 @@ math multiply [--hex-output] [...] [--version] [--help] *A group of integers to operate on.* -### Flags +### Options - term **--hex-output:** @@ -90,7 +90,7 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -### Flags +### Options - term **--version:** @@ -117,7 +117,12 @@ math stats average [--kind=] [...] [--version] [--help] *A group of floating-point values to operate on.* -### Flags +### Options + +- term **--kind=\:** + +*The kind of average to provide.* + - term **--version:** @@ -128,13 +133,6 @@ math stats average [--kind=] [...] [--version] [--help] *Show help information.* - -### Options - -- term **--kind=\:** - -*The kind of average to provide.* - ### math.stats.stdev Print the standard deviation of the values. @@ -150,7 +148,7 @@ math stats stdev [...] [--version] [--help] *A group of floating-point values to operate on.* -### Flags +### Options - term **--version:** @@ -185,18 +183,6 @@ math stats quantiles [] [] [] [< *A group of floating-point values to operate on.* -### Flags - -- term **--version:** - -*Show the version.* - - -- term **--help:** - -*Show help information.* - - ### Options - term **--file=\:** @@ -213,6 +199,16 @@ math stats quantiles [] [] [] [< - term **--custom-deprecated=\:** + +- term **--version:** + +*Show the version.* + + +- term **--help:** + +*Show help information.* + ## math.help Show subcommand help information. @@ -225,8 +221,10 @@ math help [...] [--version] - term **subcommands:** +*The subcommand(s) you want help for.* -### Flags + +### Options - term **--version:** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index fd0e2fdf6..5552294f5 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -8,7 +8,7 @@ A utility for performing maths. math [--version] [--help] ``` -### Flags +### Options **--version:** @@ -35,7 +35,7 @@ math add [--hex-output] [...] [--version] [--help] *A group of integers to operate on.* -### Flags +### Options **--hex-output:** @@ -66,7 +66,7 @@ math multiply [--hex-output] [...] [--version] [--help] *A group of integers to operate on.* -### Flags +### Options **--hex-output:** @@ -90,7 +90,7 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -### Flags +### Options **--version:** @@ -117,7 +117,12 @@ math stats average [--kind=] [...] [--version] [--help] *A group of floating-point values to operate on.* -### Flags +### Options + +**--kind=\:** + +*The kind of average to provide.* + **--version:** @@ -128,13 +133,6 @@ math stats average [--kind=] [...] [--version] [--help] *Show help information.* - -### Options - -**--kind=\:** - -*The kind of average to provide.* - ### math.stats.stdev Print the standard deviation of the values. @@ -150,7 +148,7 @@ math stats stdev [...] [--version] [--help] *A group of floating-point values to operate on.* -### Flags +### Options **--version:** @@ -185,18 +183,6 @@ math stats quantiles [] [] [] [< *A group of floating-point values to operate on.* -### Flags - -**--version:** - -*Show the version.* - - -**--help:** - -*Show help information.* - - ### Options **--file=\:** @@ -213,6 +199,16 @@ math stats quantiles [] [] [] [< **--custom-deprecated=\:** + +**--version:** + +*Show the version.* + + +**--help:** + +*Show help information.* + ## math.help Show subcommand help information. @@ -225,8 +221,10 @@ math help [...] [--version] **subcommands:** +*The subcommand(s) you want help for.* -### Flags + +### Options **--version:** diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index ceffdeb4b..10a3c8e4b 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -13,7 +13,12 @@ repeat [--count=] [--include-counter] [--help] *The phrase to repeat.* -### Flags +### Options + +- term **--count=\:** + +*The number of times to repeat 'phrase'.* + - term **--include-counter:** @@ -25,13 +30,6 @@ repeat [--count=] [--include-counter] [--help] *Show help information.* -### Options - -- term **--count=\:** - -*The number of times to repeat 'phrase'.* - - ## repeat.help Show subcommand help information. @@ -43,3 +41,5 @@ repeat help [...] ### Arguments - term **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md index 0f2377673..2af077c46 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -13,7 +13,12 @@ repeat [--count=] [--include-counter] [--help] *The phrase to repeat.* -### Flags +### Options + +**--count=\:** + +*The number of times to repeat 'phrase'.* + **--include-counter:** @@ -25,13 +30,6 @@ repeat [--count=] [--include-counter] [--help] *Show help information.* -### Options - -**--count=\:** - -*The number of times to repeat 'phrase'.* - - ## repeat.help Show subcommand help information. @@ -43,3 +41,5 @@ repeat help [...] ### Arguments **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index 0a9ed81a3..e0b2bba78 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -6,18 +6,6 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -### Flags - -- term **--verbose:** - -*Show all roll results.* - - -- term **--help:** - -*Show help information.* - - ### Options - term **--times=\:** @@ -37,6 +25,16 @@ Use this option to override the default value of a six-sided die. *A seed to use for repeatable random generation.* +- term **--verbose:** + +*Show all roll results.* + + +- term **--help:** + +*Show help information.* + + ## roll.help Show subcommand help information. @@ -48,3 +46,5 @@ roll help [...] ### Arguments - term **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md index fb8eea8a1..990c52829 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -6,18 +6,6 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -### Flags - -**--verbose:** - -*Show all roll results.* - - -**--help:** - -*Show help information.* - - ### Options **--times=\:** @@ -37,6 +25,16 @@ Use this option to override the default value of a six-sided die. *A seed to use for repeatable random generation.* +**--verbose:** + +*Show all roll results.* + + +**--help:** + +*Show help information.* + + ## roll.help Show subcommand help information. @@ -48,3 +46,5 @@ roll help [...] ### Arguments **subcommands:** + +*The subcommand(s) you want help for.* diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 4126af691..7df9be9b8 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -105,6 +105,14 @@ extension CommandInfoV0 { result += "*\(abstract)*\n\n" } + // Inject a default help description for the the `help` command positional argument 'subcommands'. + // The 'subcommands' argument is missing an abstract in ArgumentParser. + // This results in incomplete help documentation, which may confuse users. + // Since it's a positional argument named 'subcommands', it can be easily confused with actual subcommands. + if arg.identity() == "subcommands" && arg.abstract == nil { + result += "*The subcommand(s) you want help for.*\n\n" + } + // If the argument has a discussion, add it directly // If a discussion is available, it is added to provide further explanation on how the argument works. // This additional context is helpful for users to understand the full usage of the argument. @@ -150,10 +158,8 @@ extension CommandInfoV0 { switch argument.kind { case .positional: return "Arguments" - case .option: + case .option, .flag: return "Options" - case .flag: - return "Flags" } } }