From fcc8f219c369ba56a6299efaa44b8c69c7121928 Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari Date: Thu, 3 Apr 2025 18:52:49 +0330 Subject: [PATCH 01/16] [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 02/16] 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 03/16] 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 04/16] 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 05/16] 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" } } } From e8a372060c0c3ee62604e6083f0c5c758549dce9 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 20:01:49 +0330 Subject: [PATCH 06/16] fix: use monospaced code style for arguments, options, and flags in DocC flavor --- .../Snapshots/testColorDoccReference().md | 8 +-- .../testCountLinesDoccReference().md | 10 +-- .../Snapshots/testMathDoccReference().md | 64 +++++++++---------- .../Snapshots/testRepeatDoccReference().md | 10 +-- .../Snapshots/testRollDoccReference().md | 12 ++-- .../Extensions/ArgumentParser+Markdown.swift | 2 +- 6 files changed, 53 insertions(+), 53 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 08d4d6766..7cd9714e3 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -8,19 +8,19 @@ color --fav= [--second=] [--help] ### Options -- term **--fav=\:** +- term `--fav=\:` *Your favorite color.* -- term **--second=\:** +- term `--second=\:` *Your second favorite color.* This is optional. -- term **--help:** +- term `--help:` *Show help information.* @@ -35,6 +35,6 @@ color help [...] ### Arguments -- term **subcommands:** +- term `subcommands:` *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 86eb718b4..1b0d2645a 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -9,24 +9,24 @@ count-lines [] [--prefix=] [--verbose] ### Arguments -- term **input-file:** +- term `input-file:` *A file to count lines in. If omitted, counts the lines of stdin.* ### Options -- term **--prefix=\:** +- term `--prefix=\:` *Only count lines with this prefix.* -- term **--verbose:** +- term `--verbose:` *Include extra information in the output.* -- term **--help:** +- term `--help:` *Show help information.* @@ -41,6 +41,6 @@ count-lines help [...] ### Arguments -- term **subcommands:** +- term `subcommands:` *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index db970ca1a..370ef346b 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -10,12 +10,12 @@ math [--version] [--help] ### Options -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -30,24 +30,24 @@ math add [--hex-output] [...] [--version] [--help] ### Arguments -- term **values:** +- term `values:` *A group of integers to operate on.* ### Options -- term **--hex-output:** +- term `--hex-output:` *Use hexadecimal notation for the result.* -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -62,24 +62,24 @@ math multiply [--hex-output] [...] [--version] ### Arguments -- term **values:** +- term `values:` *A group of integers to operate on.* ### Options -- term **--hex-output:** +- term `--hex-output:` *Use hexadecimal notation for the result.* -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -93,12 +93,12 @@ math stats [--version] [--help] ### Options -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -114,24 +114,24 @@ math stats average [--kind=] [...] [--version] ### Arguments -- term **values:** +- term `values:` *A group of floating-point values to operate on.* ### Options -- term **--kind=\:** +- term `--kind=\:` *The kind of average to provide.* -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -145,19 +145,19 @@ math stats stdev [...] [--version] [--help] ### Arguments -- term **values:** +- term `values:` *A group of floating-point values to operate on.* ### Options -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -176,43 +176,43 @@ math stats quantiles [] [] ### Arguments -- term **one-of-four:** +- term `one-of-four:` -- term **custom-arg:** +- term `custom-arg:` -- term **custom-deprecated-arg:** +- term `custom-deprecated-arg:` -- term **values:** +- term `values:` *A group of floating-point values to operate on.* ### Options -- term **--file=\:** +- term `--file=\:` -- term **--directory=\:** +- term `--directory=\:` -- term **--shell=\:** +- term `--shell=\:` -- term **--custom=\:** +- term `--custom=\:` -- term **--custom-deprecated=\:** +- term `--custom-deprecated=\:` -- term **--version:** +- term `--version:` *Show the version.* -- term **--help:** +- term `--help:` *Show help information.* @@ -226,13 +226,13 @@ math help [...] [--version] ### Arguments -- term **subcommands:** +- term `subcommands:` *The subcommand(s) you want help for.* ### Options -- term **--version:** +- term `--version:` *Show the version.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index f3100f03d..fc6e6df8c 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -9,24 +9,24 @@ repeat [--count=] [--include-counter] ### Arguments -- term **phrase:** +- term `phrase:` *The phrase to repeat.* ### Options -- term **--count=\:** +- term `--count=\:` *How many times to repeat 'phrase'.* -- term **--include-counter:** +- term `--include-counter:` *Include a counter with each repetition.* -- term **--help:** +- term `--help:` *Show help information.* @@ -41,6 +41,6 @@ repeat help [...] ### Arguments -- term **subcommands:** +- term `subcommands:` *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index 4863480b8..faa9fe26e 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -9,29 +9,29 @@ roll [--times=] [--sides=] [--seed=] [--verbose] ### Options -- term **--times=\:** +- term `--times=\:` *Rolls the dice times.* -- term **--sides=\:** +- term `--sides=\:` *Rolls an -sided dice.* Use this option to override the default value of a six-sided die. -- term **--seed=\:** +- term `--seed=\:` *A seed to use for repeatable random generation.* -- term **--verbose:** +- term `--verbose:` *Show all roll results.* -- term **--help:** +- term `--help:` *Show help information.* @@ -46,6 +46,6 @@ roll help [...] ### Arguments -- term **subcommands:** +- term `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 58582212d..530077347 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -107,7 +107,7 @@ extension CommandInfoV0 { // The italic formatting helps to distinguish the abstract from other parts of the documentation. switch markdownStyle { case .docc: - result += "- term **\(arg.identity()):**\n\n" + result += "- term `\(arg.identity()):`\n\n" case .github: result += "**\(arg.identity()):**\n\n" } From 347fbd6fc118644baaca1c9e06758de300e1257c Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 20:11:04 +0330 Subject: [PATCH 07/16] fix: move colon outside of formatted elements in term lists --- .../Snapshots/testColorDoccReference().md | 8 +-- .../Snapshots/testColorMarkdownReference().md | 8 +-- .../testCountLinesDoccReference().md | 10 +-- .../testCountLinesMarkdownReference().md | 10 +-- .../Snapshots/testMathDoccReference().md | 64 +++++++++---------- .../Snapshots/testMathMarkdownReference().md | 64 +++++++++---------- .../Snapshots/testRepeatDoccReference().md | 10 +-- .../testRepeatMarkdownReference().md | 10 +-- .../Snapshots/testRollDoccReference().md | 12 ++-- .../Snapshots/testRollMarkdownReference().md | 12 ++-- .../Extensions/ArgumentParser+Markdown.swift | 4 +- 11 files changed, 106 insertions(+), 106 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 7cd9714e3..af514f5a3 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -8,19 +8,19 @@ color --fav= [--second=] [--help] ### Options -- term `--fav=\:` +- term `--fav=\`: *Your favorite color.* -- term `--second=\:` +- term `--second=\`: *Your second favorite color.* This is optional. -- term `--help:` +- term `--help`: *Show help information.* @@ -35,6 +35,6 @@ color help [...] ### Arguments -- term `subcommands:` +- term `subcommands`: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md index a5f059f43..a32270d90 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -8,19 +8,19 @@ color --fav= [--second=] [--help] ### Options -**--fav=\:** +**--fav=\**: *Your favorite color.* -**--second=\:** +**--second=\**: *Your second favorite color.* This is optional. -**--help:** +**--help**: *Show help information.* @@ -35,6 +35,6 @@ color help [...] ### Arguments -**subcommands:** +**subcommands**: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 1b0d2645a..4dd0a7e5c 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -9,24 +9,24 @@ count-lines [] [--prefix=] [--verbose] ### Arguments -- term `input-file:` +- term `input-file`: *A file to count lines in. If omitted, counts the lines of stdin.* ### Options -- term `--prefix=\:` +- term `--prefix=\`: *Only count lines with this prefix.* -- term `--verbose:` +- term `--verbose`: *Include extra information in the output.* -- term `--help:` +- term `--help`: *Show help information.* @@ -41,6 +41,6 @@ count-lines help [...] ### Arguments -- term `subcommands:` +- term `subcommands`: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md index 7cbaae8a2..224103425 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -8,24 +8,24 @@ count-lines [] [--prefix=] [--verbose] [--help] ### Arguments -**input-file:** +**input-file**: *A file to count lines in. If omitted, counts the lines of stdin.* ### Options -**--prefix=\:** +**--prefix=\**: *Only count lines with this prefix.* -**--verbose:** +**--verbose**: *Include extra information in the output.* -**--help:** +**--help**: *Show help information.* @@ -40,6 +40,6 @@ count-lines help [...] ### Arguments -**subcommands:** +**subcommands**: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 370ef346b..bad0bcbbd 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -10,12 +10,12 @@ math [--version] [--help] ### Options -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -30,24 +30,24 @@ math add [--hex-output] [...] [--version] [--help] ### Arguments -- term `values:` +- term `values`: *A group of integers to operate on.* ### Options -- term `--hex-output:` +- term `--hex-output`: *Use hexadecimal notation for the result.* -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -62,24 +62,24 @@ math multiply [--hex-output] [...] [--version] ### Arguments -- term `values:` +- term `values`: *A group of integers to operate on.* ### Options -- term `--hex-output:` +- term `--hex-output`: *Use hexadecimal notation for the result.* -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -93,12 +93,12 @@ math stats [--version] [--help] ### Options -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -114,24 +114,24 @@ math stats average [--kind=] [...] [--version] ### Arguments -- term `values:` +- term `values`: *A group of floating-point values to operate on.* ### Options -- term `--kind=\:` +- term `--kind=\`: *The kind of average to provide.* -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -145,19 +145,19 @@ math stats stdev [...] [--version] [--help] ### Arguments -- term `values:` +- term `values`: *A group of floating-point values to operate on.* ### Options -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -176,43 +176,43 @@ math stats quantiles [] [] ### Arguments -- term `one-of-four:` +- term `one-of-four`: -- term `custom-arg:` +- term `custom-arg`: -- term `custom-deprecated-arg:` +- term `custom-deprecated-arg`: -- term `values:` +- term `values`: *A group of floating-point values to operate on.* ### Options -- term `--file=\:` +- term `--file=\`: -- term `--directory=\:` +- term `--directory=\`: -- term `--shell=\:` +- term `--shell=\`: -- term `--custom=\:` +- term `--custom=\`: -- term `--custom-deprecated=\:` +- term `--custom-deprecated=\`: -- term `--version:` +- term `--version`: *Show the version.* -- term `--help:` +- term `--help`: *Show help information.* @@ -226,13 +226,13 @@ math help [...] [--version] ### Arguments -- term `subcommands:` +- term `subcommands`: *The subcommand(s) you want help for.* ### Options -- term `--version:` +- term `--version`: *Show the version.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index c4449289a..b50305d18 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -10,12 +10,12 @@ math [--version] [--help] ### Options -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -30,24 +30,24 @@ math add [--hex-output] [...] [--version] [--help] ### Arguments -**values:** +**values**: *A group of integers to operate on.* ### Options -**--hex-output:** +**--hex-output**: *Use hexadecimal notation for the result.* -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -61,24 +61,24 @@ math multiply [--hex-output] [...] [--version] [--help] ### Arguments -**values:** +**values**: *A group of integers to operate on.* ### Options -**--hex-output:** +**--hex-output**: *Use hexadecimal notation for the result.* -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -92,12 +92,12 @@ math stats [--version] [--help] ### Options -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -112,24 +112,24 @@ math stats average [--kind=] [...] [--version] [--help] ### Arguments -**values:** +**values**: *A group of floating-point values to operate on.* ### Options -**--kind=\:** +**--kind=\**: *The kind of average to provide.* -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -143,19 +143,19 @@ math stats stdev [...] [--version] [--help] ### Arguments -**values:** +**values**: *A group of floating-point values to operate on.* ### Options -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -172,43 +172,43 @@ math stats quantiles [] [] [] ### Arguments -**one-of-four:** +**one-of-four**: -**custom-arg:** +**custom-arg**: -**custom-deprecated-arg:** +**custom-deprecated-arg**: -**values:** +**values**: *A group of floating-point values to operate on.* ### Options -**--file=\:** +**--file=\**: -**--directory=\:** +**--directory=\**: -**--shell=\:** +**--shell=\**: -**--custom=\:** +**--custom=\**: -**--custom-deprecated=\:** +**--custom-deprecated=\**: -**--version:** +**--version**: *Show the version.* -**--help:** +**--help**: *Show help information.* @@ -222,13 +222,13 @@ math help [...] [--version] ### Arguments -**subcommands:** +**subcommands**: *The subcommand(s) you want help for.* ### Options -**--version:** +**--version**: *Show the version.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index fc6e6df8c..71c09ffad 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -9,24 +9,24 @@ repeat [--count=] [--include-counter] ### Arguments -- term `phrase:` +- term `phrase`: *The phrase to repeat.* ### Options -- term `--count=\:` +- term `--count=\`: *How many times to repeat 'phrase'.* -- term `--include-counter:` +- term `--include-counter`: *Include a counter with each repetition.* -- term `--help:` +- term `--help`: *Show help information.* @@ -41,6 +41,6 @@ repeat help [...] ### Arguments -- term `subcommands:` +- term `subcommands`: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md index 526fb9f47..27c7a7330 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -8,24 +8,24 @@ repeat [--count=] [--include-counter] [--help] ### Arguments -**phrase:** +**phrase**: *The phrase to repeat.* ### Options -**--count=\:** +**--count=\**: *How many times to repeat 'phrase'.* -**--include-counter:** +**--include-counter**: *Include a counter with each repetition.* -**--help:** +**--help**: *Show help information.* @@ -40,6 +40,6 @@ repeat help [...] ### Arguments -**subcommands:** +**subcommands**: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index faa9fe26e..d0759d441 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -9,29 +9,29 @@ roll [--times=] [--sides=] [--seed=] [--verbose] ### Options -- term `--times=\:` +- term `--times=\`: *Rolls the dice times.* -- term `--sides=\:` +- term `--sides=\`: *Rolls an -sided dice.* Use this option to override the default value of a six-sided die. -- term `--seed=\:` +- term `--seed=\`: *A seed to use for repeatable random generation.* -- term `--verbose:` +- term `--verbose`: *Show all roll results.* -- term `--help:` +- term `--help`: *Show help information.* @@ -46,6 +46,6 @@ roll help [...] ### Arguments -- term `subcommands:` +- term `subcommands`: *The subcommand(s) you want help for.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md index 4dec0c449..d4705ad6b 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -8,29 +8,29 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ### Options -**--times=\:** +**--times=\**: *Rolls the dice times.* -**--sides=\:** +**--sides=\**: *Rolls an -sided dice.* Use this option to override the default value of a six-sided die. -**--seed=\:** +**--seed=\**: *A seed to use for repeatable random generation.* -**--verbose:** +**--verbose**: *Show all roll results.* -**--help:** +**--help**: *Show help information.* @@ -45,6 +45,6 @@ roll help [...] ### Arguments -**subcommands:** +**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 530077347..d53bea697 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -107,9 +107,9 @@ extension CommandInfoV0 { // The italic formatting helps to distinguish the abstract from other parts of the documentation. switch markdownStyle { case .docc: - result += "- term `\(arg.identity()):`\n\n" + result += "- term `\(arg.identity())`:\n\n" case .github: - result += "**\(arg.identity()):**\n\n" + result += "**\(arg.identity())**:\n\n" } if let abstract = arg.abstract { From 2bc6684d598c64044a08a6515be7988006b77461 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 20:24:12 +0330 Subject: [PATCH 08/16] fix: remove unnecessary italics from argument abstracts --- .../Snapshots/testColorDoccReference().md | 6 +-- .../Snapshots/testColorMarkdownReference().md | 6 +-- .../testCountLinesDoccReference().md | 8 ++-- .../testCountLinesMarkdownReference().md | 8 ++-- .../Snapshots/testMathDoccReference().md | 46 +++++++++---------- .../Snapshots/testMathMarkdownReference().md | 46 +++++++++---------- .../Snapshots/testRepeatDoccReference().md | 8 ++-- .../testRepeatMarkdownReference().md | 8 ++-- .../Snapshots/testRollDoccReference().md | 10 ++-- .../Snapshots/testRollMarkdownReference().md | 10 ++-- .../Extensions/ArgumentParser+Markdown.swift | 2 +- 11 files changed, 79 insertions(+), 79 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index af514f5a3..9b3832805 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -10,19 +10,19 @@ color --fav= [--second=] [--help] - term `--fav=\`: -*Your favorite color.* +Your favorite color. - term `--second=\`: -*Your second favorite color.* +Your second favorite color. This is optional. - term `--help`: -*Show help information.* +Show help information. ## color.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md index a32270d90..ac805d1f5 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -10,19 +10,19 @@ color --fav= [--second=] [--help] **--fav=\**: -*Your favorite color.* +Your favorite color. **--second=\**: -*Your second favorite color.* +Your second favorite color. This is optional. **--help**: -*Show help information.* +Show help information. ## color.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 4dd0a7e5c..ee549a2f5 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -11,24 +11,24 @@ count-lines [] [--prefix=] [--verbose] - term `input-file`: -*A file to count lines in. If omitted, counts the lines of stdin.* +A file to count lines in. If omitted, counts the lines of stdin. ### Options - term `--prefix=\`: -*Only count lines with this prefix.* +Only count lines with this prefix. - term `--verbose`: -*Include extra information in the output.* +Include extra information in the output. - term `--help`: -*Show help information.* +Show help information. ## count-lines.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md index 224103425..f24f24e84 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -10,24 +10,24 @@ count-lines [] [--prefix=] [--verbose] [--help] **input-file**: -*A file to count lines in. If omitted, counts the lines of stdin.* +A file to count lines in. If omitted, counts the lines of stdin. ### Options **--prefix=\**: -*Only count lines with this prefix.* +Only count lines with this prefix. **--verbose**: -*Include extra information in the output.* +Include extra information in the output. **--help**: -*Show help information.* +Show help information. ## count-lines.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index bad0bcbbd..f59f7dabe 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -12,12 +12,12 @@ math [--version] [--help] - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ## math.add @@ -32,24 +32,24 @@ math add [--hex-output] [...] [--version] [--help] - term `values`: -*A group of integers to operate on.* +A group of integers to operate on. ### Options - term `--hex-output`: -*Use hexadecimal notation for the result.* +Use hexadecimal notation for the result. - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ## math.multiply @@ -64,24 +64,24 @@ math multiply [--hex-output] [...] [--version] - term `values`: -*A group of integers to operate on.* +A group of integers to operate on. ### Options - term `--hex-output`: -*Use hexadecimal notation for the result.* +Use hexadecimal notation for the result. - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ## math.stats @@ -95,12 +95,12 @@ math stats [--version] [--help] - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ### math.stats.average @@ -116,24 +116,24 @@ math stats average [--kind=] [...] [--version] - term `values`: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options - term `--kind=\`: -*The kind of average to provide.* +The kind of average to provide. - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ### math.stats.stdev @@ -147,19 +147,19 @@ math stats stdev [...] [--version] [--help] - term `values`: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ### math.stats.quantiles @@ -187,7 +187,7 @@ math stats quantiles [] [] - term `values`: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options @@ -209,12 +209,12 @@ math stats quantiles [] [] - term `--version`: -*Show the version.* +Show the version. - term `--help`: -*Show help information.* +Show help information. ## math.help @@ -235,4 +235,4 @@ math help [...] [--version] - term `--version`: -*Show the version.* +Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index b50305d18..fc57b9f04 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -12,12 +12,12 @@ math [--version] [--help] **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ## math.add @@ -32,24 +32,24 @@ math add [--hex-output] [...] [--version] [--help] **values**: -*A group of integers to operate on.* +A group of integers to operate on. ### Options **--hex-output**: -*Use hexadecimal notation for the result.* +Use hexadecimal notation for the result. **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ## math.multiply @@ -63,24 +63,24 @@ math multiply [--hex-output] [...] [--version] [--help] **values**: -*A group of integers to operate on.* +A group of integers to operate on. ### Options **--hex-output**: -*Use hexadecimal notation for the result.* +Use hexadecimal notation for the result. **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ## math.stats @@ -94,12 +94,12 @@ math stats [--version] [--help] **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ### math.stats.average @@ -114,24 +114,24 @@ math stats average [--kind=] [...] [--version] [--help] **values**: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options **--kind=\**: -*The kind of average to provide.* +The kind of average to provide. **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ### math.stats.stdev @@ -145,19 +145,19 @@ math stats stdev [...] [--version] [--help] **values**: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ### math.stats.quantiles @@ -183,7 +183,7 @@ math stats quantiles [] [] [] **values**: -*A group of floating-point values to operate on.* +A group of floating-point values to operate on. ### Options @@ -205,12 +205,12 @@ math stats quantiles [] [] [] **--version**: -*Show the version.* +Show the version. **--help**: -*Show help information.* +Show help information. ## math.help @@ -231,4 +231,4 @@ math help [...] [--version] **--version**: -*Show the version.* +Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 71c09ffad..94fed21db 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -11,24 +11,24 @@ repeat [--count=] [--include-counter] - term `phrase`: -*The phrase to repeat.* +The phrase to repeat. ### Options - term `--count=\`: -*How many times to repeat 'phrase'.* +How many times to repeat 'phrase'. - term `--include-counter`: -*Include a counter with each repetition.* +Include a counter with each repetition. - term `--help`: -*Show help information.* +Show help information. ## repeat.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md index 27c7a7330..723fbf442 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -10,24 +10,24 @@ repeat [--count=] [--include-counter] [--help] **phrase**: -*The phrase to repeat.* +The phrase to repeat. ### Options **--count=\**: -*How many times to repeat 'phrase'.* +How many times to repeat 'phrase'. **--include-counter**: -*Include a counter with each repetition.* +Include a counter with each repetition. **--help**: -*Show help information.* +Show help information. ## repeat.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index d0759d441..114e770b1 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -11,29 +11,29 @@ roll [--times=] [--sides=] [--seed=] [--verbose] - term `--times=\`: -*Rolls the dice times.* +Rolls the dice times. - term `--sides=\`: -*Rolls an -sided dice.* +Rolls an -sided dice. Use this option to override the default value of a six-sided die. - term `--seed=\`: -*A seed to use for repeatable random generation.* +A seed to use for repeatable random generation. - term `--verbose`: -*Show all roll results.* +Show all roll results. - term `--help`: -*Show help information.* +Show help information. ## roll.help diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md index d4705ad6b..87d790daa 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -10,29 +10,29 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] **--times=\**: -*Rolls the dice times.* +Rolls the dice times. **--sides=\**: -*Rolls an -sided dice.* +Rolls an -sided dice. Use this option to override the default value of a six-sided die. **--seed=\**: -*A seed to use for repeatable random generation.* +A seed to use for repeatable random generation. **--verbose**: -*Show all roll results.* +Show all roll results. **--help**: -*Show help information.* +Show help information. ## roll.help diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index d53bea697..7c6776bdd 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -113,7 +113,7 @@ extension CommandInfoV0 { } if let abstract = arg.abstract { - result += "*\(abstract)*\n\n" + result += "\(abstract)\n\n" } // Inject a default help description for the the `help` command positional argument 'subcommands'. From 4679e8a135b52470d67991de93b7091bb461a98e Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 20:44:11 +0330 Subject: [PATCH 09/16] fix: refine argument rendering by removing unnecessary newlines --- .../Snapshots/testColorDoccReference().md | 7 --- .../Snapshots/testColorMarkdownReference().md | 7 --- .../testCountLinesDoccReference().md | 9 ---- .../testCountLinesMarkdownReference().md | 9 ---- .../Snapshots/testMathDoccReference().md | 49 ------------------- .../Snapshots/testMathMarkdownReference().md | 49 ------------------- .../Snapshots/testRepeatDoccReference().md | 9 ---- .../testRepeatMarkdownReference().md | 9 ---- .../Snapshots/testRollDoccReference().md | 11 ----- .../Snapshots/testRollMarkdownReference().md | 11 ----- .../Extensions/ArgumentParser+Markdown.swift | 6 +-- 11 files changed, 3 insertions(+), 173 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 9b3832805..275f5e8b5 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -9,22 +9,16 @@ color --fav= [--second=] [--help] ### Options - term `--fav=\`: - Your favorite color. - - term `--second=\`: - Your second favorite color. - This is optional. - term `--help`: - Show help information. - ## color.help Show subcommand help information. @@ -36,5 +30,4 @@ 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 ac805d1f5..c5b5c8646 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -9,22 +9,16 @@ color --fav= [--second=] [--help] ### Options **--fav=\**: - Your favorite color. - **--second=\**: - Your second favorite color. - This is optional. **--help**: - Show help information. - ## color.help Show subcommand help information. @@ -36,5 +30,4 @@ 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 ee549a2f5..8ce578700 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -10,27 +10,19 @@ count-lines [] [--prefix=] [--verbose] ### Arguments - term `input-file`: - A file to count lines in. If omitted, counts the lines of stdin. - ### Options - term `--prefix=\`: - Only count lines with this prefix. - - term `--verbose`: - Include extra information in the output. - - term `--help`: - Show help information. - ## count-lines.help Show subcommand help information. @@ -42,5 +34,4 @@ 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 f24f24e84..e15933230 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -9,27 +9,19 @@ count-lines [] [--prefix=] [--verbose] [--help] ### Arguments **input-file**: - A file to count lines in. If omitted, counts the lines of stdin. - ### Options **--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. @@ -41,5 +33,4 @@ 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 f59f7dabe..04c8d82cc 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -11,15 +11,11 @@ math [--version] [--help] ### Options - term `--version`: - Show the version. - - term `--help`: - Show help information. - ## math.add Print the sum of the values. @@ -31,24 +27,17 @@ math add [--hex-output] [...] [--version] [--help] ### Arguments - term `values`: - A group of integers to operate on. - ### Options - term `--hex-output`: - Use hexadecimal notation for the result. - - term `--version`: - Show the version. - - term `--help`: - Show help information. ## math.multiply @@ -63,24 +52,17 @@ math multiply [--hex-output] [...] [--version] ### Arguments - term `values`: - A group of integers to operate on. - ### Options - term `--hex-output`: - Use hexadecimal notation for the result. - - term `--version`: - Show the version. - - term `--help`: - Show help information. ## math.stats @@ -94,15 +76,11 @@ math stats [--version] [--help] ### Options - term `--version`: - Show the version. - - term `--help`: - Show help information. - ### math.stats.average Print the average of the values. @@ -115,24 +93,17 @@ math stats average [--kind=] [...] [--version] ### Arguments - term `values`: - A group of floating-point values to operate on. - ### Options - term `--kind=\`: - The kind of average to provide. - - term `--version`: - Show the version. - - term `--help`: - Show help information. ### math.stats.stdev @@ -146,19 +117,14 @@ math stats stdev [...] [--version] [--help] ### Arguments - term `values`: - A group of floating-point values to operate on. - ### Options - term `--version`: - Show the version. - - term `--help`: - Show help information. ### math.stats.quantiles @@ -178,42 +144,29 @@ math stats quantiles [] [] - term `one-of-four`: - - term `custom-arg`: - - term `custom-deprecated-arg`: - - term `values`: - A group of floating-point values to operate on. - ### Options - term `--file=\`: - - term `--directory=\`: - - term `--shell=\`: - - term `--custom=\`: - - term `--custom-deprecated=\`: - - term `--version`: - Show the version. - - term `--help`: - Show help information. ## math.help @@ -227,12 +180,10 @@ math help [...] [--version] ### Arguments - term `subcommands`: - *The subcommand(s) you want help for.* ### Options - term `--version`: - Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index fc57b9f04..7903fd41c 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -11,15 +11,11 @@ math [--version] [--help] ### Options **--version**: - Show the version. - **--help**: - Show help information. - ## math.add Print the sum of the values. @@ -31,24 +27,17 @@ math add [--hex-output] [...] [--version] [--help] ### Arguments **values**: - A group of integers to operate on. - ### Options **--hex-output**: - Use hexadecimal notation for the result. - **--version**: - Show the version. - **--help**: - Show help information. ## math.multiply @@ -62,24 +51,17 @@ math multiply [--hex-output] [...] [--version] [--help] ### Arguments **values**: - A group of integers to operate on. - ### Options **--hex-output**: - Use hexadecimal notation for the result. - **--version**: - Show the version. - **--help**: - Show help information. ## math.stats @@ -93,15 +75,11 @@ math stats [--version] [--help] ### Options **--version**: - Show the version. - **--help**: - Show help information. - ### math.stats.average Print the average of the values. @@ -113,24 +91,17 @@ math stats average [--kind=] [...] [--version] [--help] ### Arguments **values**: - A group of floating-point values to operate on. - ### Options **--kind=\**: - The kind of average to provide. - **--version**: - Show the version. - **--help**: - Show help information. ### math.stats.stdev @@ -144,19 +115,14 @@ math stats stdev [...] [--version] [--help] ### Arguments **values**: - A group of floating-point values to operate on. - ### Options **--version**: - Show the version. - **--help**: - Show help information. ### math.stats.quantiles @@ -174,42 +140,29 @@ math stats quantiles [] [] [] **one-of-four**: - **custom-arg**: - **custom-deprecated-arg**: - **values**: - A group of floating-point values to operate on. - ### Options **--file=\**: - **--directory=\**: - **--shell=\**: - **--custom=\**: - **--custom-deprecated=\**: - **--version**: - Show the version. - **--help**: - Show help information. ## math.help @@ -223,12 +176,10 @@ math help [...] [--version] ### Arguments **subcommands**: - *The subcommand(s) you want help for.* ### Options **--version**: - Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 94fed21db..134b714a4 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -10,27 +10,19 @@ repeat [--count=] [--include-counter] ### Arguments - term `phrase`: - The phrase to repeat. - ### Options - term `--count=\`: - How many times to repeat 'phrase'. - - term `--include-counter`: - Include a counter with each repetition. - - term `--help`: - Show help information. - ## repeat.help Show subcommand help information. @@ -42,5 +34,4 @@ 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 723fbf442..da79aefff 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -9,27 +9,19 @@ repeat [--count=] [--include-counter] [--help] ### Arguments **phrase**: - The phrase to repeat. - ### Options **--count=\**: - How many times to repeat 'phrase'. - **--include-counter**: - Include a counter with each repetition. - **--help**: - Show help information. - ## repeat.help Show subcommand help information. @@ -41,5 +33,4 @@ 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 114e770b1..a339323dc 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -10,32 +10,22 @@ roll [--times=] [--sides=] [--seed=] [--verbose] ### Options - term `--times=\`: - Rolls the dice times. - - term `--sides=\`: - Rolls an -sided dice. - Use this option to override the default value of a six-sided die. - term `--seed=\`: - 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. @@ -47,5 +37,4 @@ 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 87d790daa..25df6170e 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -9,32 +9,22 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ### Options **--times=\**: - Rolls the dice times. - **--sides=\**: - Rolls an -sided dice. - Use this option to override the default value of a six-sided die. **--seed=\**: - A seed to use for repeatable random generation. - **--verbose**: - Show all roll results. - **--help**: - Show help information. - ## roll.help Show subcommand help information. @@ -46,5 +36,4 @@ 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 7c6776bdd..e5a7b4abf 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -107,13 +107,13 @@ extension CommandInfoV0 { // The italic formatting helps to distinguish the abstract from other parts of the documentation. switch markdownStyle { case .docc: - result += "- term `\(arg.identity())`:\n\n" + result += "- term `\(arg.identity())`:\n" case .github: - result += "**\(arg.identity())**:\n\n" + result += "**\(arg.identity())**:\n" } if let abstract = arg.abstract { - result += "\(abstract)\n\n" + result += "\(abstract)\n" } // Inject a default help description for the the `help` command positional argument 'subcommands'. From 3ae506ef3979dbdc1a2677fba9e123e352e4b6a9 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 20:47:33 +0330 Subject: [PATCH 10/16] refactor: use `let` instead of `var` to signal immutability --- Tools/generate-docc-reference/GenerateDoccReference.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Tools/generate-docc-reference/GenerateDoccReference.swift b/Tools/generate-docc-reference/GenerateDoccReference.swift index 7bb056df9..9453df3d6 100644 --- a/Tools/generate-docc-reference/GenerateDoccReference.swift +++ b/Tools/generate-docc-reference/GenerateDoccReference.swift @@ -109,7 +109,7 @@ struct GenerateDoccReference: ParsableCommand { throw GenerateDoccReferenceError.unableToParseToolOutput(error: error) } - var toolInfo: ToolInfoV0 + let toolInfo: ToolInfoV0 do { toolInfo = try JSONDecoder().decode(ToolInfoV0.self, from: data) From 2be475e0fa1bfdc503d07382336afc3292b60a3f Mon Sep 17 00:00:00 2001 From: Ashkan Ebtekari <56440241+Chamepp@users.noreply.github.com> Date: Tue, 30 Sep 2025 21:12:03 +0330 Subject: [PATCH 11/16] refactor: rename assignSectionTitle(to:) to sectionTitle(for:) for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: David Rönnqvist --- .../Extensions/ArgumentParser+Markdown.swift | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index e5a7b4abf..5970e0b5b 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -183,8 +183,8 @@ extension CommandInfoV0 { return multilineString } - // Assign a default section title based on the arguments types - func assignSectionTitle(to argument: ArgumentInfoV0) -> String { + // Returns the default section title for the provided the argument. + func sectionTitle(for argument: ArgumentInfoV0) -> String { if let sectionTitle = argument.sectionTitle { return sectionTitle } else { From 71d5903c5355647290aa28af4920d828fbf96fe5 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 21:55:20 +0330 Subject: [PATCH 12/16] refactor: make sectionTitle(for:) a fileprivate computed property on ArgumentInfoV0 extension --- .../Extensions/ArgumentParser+Markdown.swift | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 5970e0b5b..1cab97c61 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -84,7 +84,7 @@ extension CommandInfoV0 { grouping: args.filter { $0.shouldDisplay } - ) { self.assignSectionTitle(to: $0) } + ) { $0.sectionTitleDefault } // Iterate through the grouped arguments, sorted by section title // Sorting ensures that the sections appear in a clear, predictable order in the final documentation. @@ -182,20 +182,6 @@ extension CommandInfoV0 { } return multilineString } - - // Returns the default section title for the provided the argument. - func sectionTitle(for argument: ArgumentInfoV0) -> String { - if let sectionTitle = argument.sectionTitle { - return sectionTitle - } else { - switch argument.kind { - case .positional: - return "Arguments" - case .option, .flag: - return "Options" - } - } - } } @@ -268,4 +254,18 @@ extension ArgumentInfoV0 { } return inner } + + /// Returns the default section title for this argument. + fileprivate var sectionTitleDefault: String { + if let sectionTitle = self.sectionTitle { + return sectionTitle + } else { + switch self.kind { + case .positional: + return "Arguments" + case .option, .flag: + return "Options" + } + } + } } From 0b84e4c7234f1b14b89073ec016abf2a4c69df55 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Tue, 30 Sep 2025 22:12:24 +0330 Subject: [PATCH 13/16] fix: align default subcommands abstract with CLI --help output --- .../Snapshots/testColorDoccReference().md | 2 +- .../Snapshots/testColorMarkdownReference().md | 2 +- .../Snapshots/testCountLinesDoccReference().md | 2 +- .../Snapshots/testCountLinesMarkdownReference().md | 2 +- .../Snapshots/testMathDoccReference().md | 3 +-- .../Snapshots/testMathMarkdownReference().md | 3 +-- .../Snapshots/testRepeatDoccReference().md | 2 +- .../Snapshots/testRepeatMarkdownReference().md | 2 +- .../Snapshots/testRollDoccReference().md | 2 +- .../Snapshots/testRollMarkdownReference().md | 2 +- .../Extensions/ArgumentParser+Markdown.swift | 2 +- 11 files changed, 11 insertions(+), 13 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 275f5e8b5..a5360d913 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -30,4 +30,4 @@ color help [...] ### Arguments - term `subcommands`: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md index c5b5c8646..6e9d8460e 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -30,4 +30,4 @@ color help [...] ### Arguments **subcommands**: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 8ce578700..b4cc3de45 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -34,4 +34,4 @@ count-lines help [...] ### Arguments - term `subcommands`: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md index e15933230..c26cfa4f0 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -33,4 +33,4 @@ count-lines help [...] ### Arguments **subcommands**: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 04c8d82cc..34406417f 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -180,8 +180,7 @@ math help [...] [--version] ### Arguments - term `subcommands`: -*The subcommand(s) you want help for.* - +*Show help information.* ### Options diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index 7903fd41c..aea0ee8dc 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -176,8 +176,7 @@ math help [...] [--version] ### Arguments **subcommands**: -*The subcommand(s) you want help for.* - +*Show help information.* ### Options diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 134b714a4..af0790985 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -34,4 +34,4 @@ repeat help [...] ### Arguments - term `subcommands`: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md index da79aefff..341e9082d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -33,4 +33,4 @@ repeat help [...] ### Arguments **subcommands**: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index a339323dc..f4453ea1d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -37,4 +37,4 @@ roll help [...] ### Arguments - term `subcommands`: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md index 25df6170e..043c6b5b9 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -36,4 +36,4 @@ roll help [...] ### Arguments **subcommands**: -*The subcommand(s) you want help for.* +*Show help information.* diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 1cab97c61..8223b7174 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -121,7 +121,7 @@ extension CommandInfoV0 { // 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" + result += "*Show help information.*\n" } // If the argument has a discussion, add it directly From fe07123e43d20d8f159656548061de016a4a7956 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Sat, 4 Oct 2025 18:02:22 +0330 Subject: [PATCH 14/16] test: add custom section titles to math.quantiles for testing documentation sorting --- Examples/math/Math.swift | 112 +++++++++----- .../MathExampleTests.swift | 27 ++-- .../testMathBashCompletionScript().bash | 32 ++-- .../testMathFishCompletionScript().fish | 17 +- .../testMathZshCompletionScript().zsh | 17 +- .../Snapshots/testMathDoccReference().md | 41 +++-- .../Snapshots/testMathMarkdownReference().md | 41 +++-- .../Snapshots/testMathMultiPageManual().mdoc | 21 ++- .../Snapshots/testMathSinglePageManual().mdoc | 14 +- .../Snapshots/testMathDumpHelp().json | 146 ++++++++++-------- .../Snapshots/testMathStatsDumpHelp().json | 146 ++++++++++-------- 11 files changed, 364 insertions(+), 250 deletions(-) diff --git a/Examples/math/Math.swift b/Examples/math/Math.swift index eec24fee7..59ae7b8c7 100644 --- a/Examples/math/Math.swift +++ b/Examples/math/Math.swift @@ -193,66 +193,100 @@ extension Math.Statistics { static let configuration = CommandConfiguration( abstract: "Print the quantiles of the values (TBD).") - @Argument( - completion: .list(["alphabet", "alligator", "branch", "braggart"])) - var oneOfFour: String? - - @Argument( - completion: .custom { _, _, _ in - ["alabaster", "breakfast", "crunch", "crash"] - } - ) - var customArg: String? + @Argument(help: "A group of floating-point values to operate on.") + var values: [Double] = [] - @Argument( - completion: .custom { _ in ["alabaster", "breakfast", "crunch", "crash"] } + @Option( + help: "Input file or directory to process (default section).", + completion: .file(extensions: ["txt", "md"]) ) - var customDeprecatedArg: String? + var file: String? - @Argument(help: "A group of floating-point values to operate on.") - var values: [Double] = [] + struct InputOptions: ParsableArguments { + @Option( + help: "Choose one of four predefined options", + completion: .list(["alphabet", "alligator", "branch", "braggart"]) + ) + var oneOfFour: String? + + @Option( + help: "Custom argument", + completion: .custom { _, _, _ in ["alabaster", "breakfast", "crunch", "crash"] } + ) + var customArg: String? + + @Option( + help: "Deprecated custom argument", + completion: .custom { _ in ["alabaster", "breakfast", "crunch", "crash"] } + ) + var customDeprecatedArg: String? + } // These args and the validation method are for testing exit codes: - @Flag(help: .hidden) - var testSuccessExitCode = false - @Flag(help: .hidden) - var testFailureExitCode = false - @Flag(help: .hidden) - var testValidationExitCode = false - @Option(help: .hidden) - var testCustomExitCode: Int32? + struct HiddenOptions: ParsableArguments { + @Flag(help: .hidden) + var testSuccessExitCode = false + + @Flag(help: .hidden) + var testFailureExitCode = false + + @Flag(help: .hidden) + var testValidationExitCode = false + + @Option(help: .hidden) + var testCustomExitCode: Int32? + } // These args are for testing custom completion scripts: - @Option(completion: .file(extensions: ["txt", "md"])) - var file: String? - @Option(completion: .directory) - var directory: String? + struct ShellOptions: ParsableArguments { + @Option( + help: "Run a shell command for input or completion", + completion: .shellCommand("head -100 /usr/share/dict/words | tail -50") + ) + var shell: String? + } - @Option( - completion: .shellCommand("head -100 /usr/share/dict/words | tail -50") - ) - var shell: String? + struct CustomOptions: ParsableArguments { + @Option( + help: "Custom user-provided option with dynamic completion", + completion: .custom(customCompletion) + ) + var custom: String? + + @Option( + help: "Deprecated custom option", + completion: .custom(customDeprecatedCompletion) + ) + var customDeprecated: String? + } + + // Assinging custom section titles for option groups + @OptionGroup(title: "Input Options") + var input: InputOptions + + @OptionGroup(title: "Hidden / Testing Options") + var hidden: HiddenOptions - @Option(completion: .custom(customCompletion)) - var custom: String? + @OptionGroup(title: "Shell Options") + var shell: ShellOptions - @Option(completion: .custom(customDeprecatedCompletion)) - var customDeprecated: String? + @OptionGroup(title: "Custom Options") + var custom: CustomOptions func validate() throws { - if testSuccessExitCode { + if hidden.testSuccessExitCode { throw ExitCode.success } - if testFailureExitCode { + if hidden.testFailureExitCode { throw ExitCode.failure } - if testValidationExitCode { + if hidden.testValidationExitCode { throw ExitCode.validationFailure } - if let exitCode = testCustomExitCode { + if let exitCode = hidden.testCustomExitCode { throw ExitCode(exitCode) } } diff --git a/Tests/ArgumentParserExampleTests/MathExampleTests.swift b/Tests/ArgumentParserExampleTests/MathExampleTests.swift index 64f1ac0e0..e6cba80e8 100644 --- a/Tests/ArgumentParserExampleTests/MathExampleTests.swift +++ b/Tests/ArgumentParserExampleTests/MathExampleTests.swift @@ -107,20 +107,29 @@ final class MathExampleTests: XCTestCase { let helpText = """ OVERVIEW: Print the quantiles of the values (TBD). - USAGE: math stats quantiles [] [] [] [ ...] [--file ] [--directory ] [--shell ] [--custom ] [--custom-deprecated ] + USAGE: math stats quantiles [ ...] [--file ] [--one-of-four ] [--custom-arg ] [--custom-deprecated-arg ] [--shell ] [--custom ] [--custom-deprecated ] ARGUMENTS: - - - A group of floating-point values to operate on. - OPTIONS: - --file - --directory - --shell - --custom + INPUT OPTIONS: + --one-of-four + Choose one of four predefined options + --custom-arg + Custom argument + --custom-deprecated-arg + Deprecated custom argument + + SHELL OPTIONS: + --shell Run a shell command for input or completion + + CUSTOM OPTIONS: + --custom Custom user-provided option with dynamic completion --custom-deprecated + Deprecated custom option + + OPTIONS: + --file Input file or directory to process (default section). --version Show the version. -h, --help Show help information. diff --git a/Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash b/Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash index 2993a5151..6411949bc 100644 --- a/Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash +++ b/Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash @@ -233,8 +233,8 @@ _math_stats_stdev() { _math_stats_quantiles() { flags=(--version -h --help) - options=(--file --directory --shell --custom --custom-deprecated) - __math_offer_flags_options 4 + options=(--file --one-of-four --custom-arg --custom-deprecated-arg --shell --custom --custom-deprecated) + __math_offer_flags_options 1 # Offer option value completions case "${prev}" in @@ -242,8 +242,16 @@ _math_stats_quantiles() { __math_add_completions -o plusdirs -fX '!*.@(txt|md)' return ;; - '--directory') - __math_add_completions -d + '--one-of-four') + __math_add_completions -W 'alphabet'$'\n''alligator'$'\n''branch'$'\n''braggart' + return + ;; + '--custom-arg') + __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- --custom-arg "${COMP_CWORD}" "$(__math_cursor_index_in_current_word)")" + return + ;; + '--custom-deprecated-arg') + __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- --custom-deprecated-arg)" return ;; '--shell') @@ -259,22 +267,6 @@ _math_stats_quantiles() { return ;; esac - - # Offer positional completions - case "${positional_number}" in - 1) - __math_add_completions -W 'alphabet'$'\n''alligator'$'\n''branch'$'\n''braggart' - return - ;; - 2) - __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- positional@1 "${COMP_CWORD}" "$(__math_cursor_index_in_current_word)")" - return - ;; - 3) - __math_add_completions -W "$(__math_custom_complete ---completion stats quantiles -- positional@2)" - return - ;; - esac } _math_help() { diff --git a/Tests/ArgumentParserExampleTests/Snapshots/testMathFishCompletionScript().fish b/Tests/ArgumentParserExampleTests/Snapshots/testMathFishCompletionScript().fish index ee346a9d4..bf37f4962 100644 --- a/Tests/ArgumentParserExampleTests/Snapshots/testMathFishCompletionScript().fish +++ b/Tests/ArgumentParserExampleTests/Snapshots/testMathFishCompletionScript().fish @@ -19,7 +19,7 @@ function __math_should_offer_completions_for -a expected_commands -a expected_po case 'stdev' __math_parse_subcommand -r 1 'version' 'h/help' case 'quantiles' - __math_parse_subcommand -r 4 'file=' 'directory=' 'shell=' 'custom=' 'custom-deprecated=' 'version' 'h/help' + __math_parse_subcommand -r 1 'file=' 'one-of-four=' 'custom-arg=' 'custom-deprecated-arg=' 'shell=' 'custom=' 'custom-deprecated=' 'version' 'h/help' end case 'help' __math_parse_subcommand -r 1 'version' @@ -100,14 +100,13 @@ complete -c 'math' -n '__math_should_offer_completions_for "math stats average"' complete -c 'math' -n '__math_should_offer_completions_for "math stats average"' -s 'h' -l 'help' -d 'Show help information.' complete -c 'math' -n '__math_should_offer_completions_for "math stats stdev"' -l 'version' -d 'Show the version.' complete -c 'math' -n '__math_should_offer_completions_for "math stats stdev"' -s 'h' -l 'help' -d 'Show help information.' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles" 1' -fka 'alphabet alligator branch braggart' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles" 2' -fka '(__math_custom_completion ---completion stats quantiles -- positional@1 (count (__math_tokens -pc)) (__math_tokens -tC))' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles" 3' -fka '(__math_custom_completion ---completion stats quantiles -- positional@2)' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'file' -rfa '(set -l exts \'txt\' \'md\';for p in (string match -e -- \'*/\' (commandline -t);or printf \n)*.{$exts};printf %s\n $p;end;__fish_complete_directories (commandline -t) \'\')' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'directory' -rfa '(__math_complete_directories)' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'shell' -rfka '(head -100 /usr/share/dict/words | tail -50)' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom (count (__math_tokens -pc)) (__math_tokens -tC))' -complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom-deprecated' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom-deprecated)' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'file' -d 'Input file or directory to process (default section).' -rfa '(set -l exts \'txt\' \'md\';for p in (string match -e -- \'*/\' (commandline -t);or printf \n)*.{$exts};printf %s\n $p;end;__fish_complete_directories (commandline -t) \'\')' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'one-of-four' -d 'Choose one of four predefined options' -rfka 'alphabet alligator branch braggart' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom-arg' -d 'Custom argument' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom-arg (count (__math_tokens -pc)) (__math_tokens -tC))' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom-deprecated-arg' -d 'Deprecated custom argument' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom-deprecated-arg)' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'shell' -d 'Run a shell command for input or completion' -rfka '(head -100 /usr/share/dict/words | tail -50)' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom' -d 'Custom user-provided option with dynamic completion' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom (count (__math_tokens -pc)) (__math_tokens -tC))' +complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'custom-deprecated' -d 'Deprecated custom option' -rfka '(__math_custom_completion ---completion stats quantiles -- --custom-deprecated)' complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -l 'version' -d 'Show the version.' complete -c 'math' -n '__math_should_offer_completions_for "math stats quantiles"' -s 'h' -l 'help' -d 'Show help information.' complete -c 'math' -n '__math_should_offer_completions_for "math help"' -l 'version' -d 'Show the version.' diff --git a/Tests/ArgumentParserExampleTests/Snapshots/testMathZshCompletionScript().zsh b/Tests/ArgumentParserExampleTests/Snapshots/testMathZshCompletionScript().zsh index 2e47fa2c1..04885ef8a 100644 --- a/Tests/ArgumentParserExampleTests/Snapshots/testMathZshCompletionScript().zsh +++ b/Tests/ArgumentParserExampleTests/Snapshots/testMathZshCompletionScript().zsh @@ -153,17 +153,16 @@ _math_stats_stdev() { _math_stats_quantiles() { local -i ret=1 - local -ar _one_of_four=('alphabet' 'alligator' 'branch' 'braggart') + local -ar ___one_of_four=('alphabet' 'alligator' 'branch' 'braggart') local -ar arg_specs=( - ':one-of-four:{__math_complete "${_one_of_four[@]}"}' - ':custom-arg:{__math_custom_complete ---completion stats quantiles -- positional@1 "${current_word_index}" "$(__math_cursor_index_in_current_word)"}' - ':custom-deprecated-arg:{__math_custom_complete ---completion stats quantiles -- positional@2}' '*:values:' - '--file:file:_files -g '\''*.txt *.md'\''' - '--directory:directory:_files -/' - '--shell:shell:{local -a list;list=(${(f)"$(head -100 /usr/share/dict/words | tail -50)"});_describe -V "" list}' - '--custom:custom:{__math_custom_complete ---completion stats quantiles -- --custom "${current_word_index}" "$(__math_cursor_index_in_current_word)"}' - '--custom-deprecated:custom-deprecated:{__math_custom_complete ---completion stats quantiles -- --custom-deprecated}' + '--file[Input file or directory to process (default section).]:file:_files -g '\''*.txt *.md'\''' + '--one-of-four[Choose one of four predefined options]:one-of-four:{__math_complete "${___one_of_four[@]}"}' + '--custom-arg[Custom argument]:custom-arg:{__math_custom_complete ---completion stats quantiles -- --custom-arg "${current_word_index}" "$(__math_cursor_index_in_current_word)"}' + '--custom-deprecated-arg[Deprecated custom argument]:custom-deprecated-arg:{__math_custom_complete ---completion stats quantiles -- --custom-deprecated-arg}' + '--shell[Run a shell command for input or completion]:shell:{local -a list;list=(${(f)"$(head -100 /usr/share/dict/words | tail -50)"});_describe -V "" list}' + '--custom[Custom user-provided option with dynamic completion]:custom:{__math_custom_complete ---completion stats quantiles -- --custom "${current_word_index}" "$(__math_cursor_index_in_current_word)"}' + '--custom-deprecated[Deprecated custom option]:custom-deprecated:{__math_custom_complete ---completion stats quantiles -- --custom-deprecated}' '--version[Show the version.]' '(-h --help)'{-h,--help}'[Show help information.]' ) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 34406417f..9c06d8378 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -132,36 +132,42 @@ Show help information. Print the quantiles of the values (TBD). ``` -math stats quantiles [] [] - [] [...] [--file=] - [--directory=] [--shell=] - [--custom=] +math stats quantiles [...] [--file=] + [--one-of-four=] [--custom-arg=] + [--custom-deprecated-arg=] + [--shell=] [--custom=] [--custom-deprecated=] [--version] [--help] ``` ### Arguments -- term `one-of-four`: +- term `values`: +A group of floating-point values to operate on. -- term `custom-arg`: +### Custom Options -- term `custom-deprecated-arg`: +- term `--custom=\`: +Custom user-provided option with dynamic completion -- term `values`: -A group of floating-point values to operate on. +- term `--custom-deprecated=\`: +Deprecated custom option -### Options +### Input Options -- term `--file=\`: +- term `--one-of-four=\`: +Choose one of four predefined options -- term `--directory=\`: +- term `--custom-arg=\`: +Custom argument -- term `--shell=\`: +- term `--custom-deprecated-arg=\`: +Deprecated custom argument -- term `--custom=\`: +### Options -- term `--custom-deprecated=\`: +- term `--file=\`: +Input file or directory to process (default section). - term `--version`: Show the version. @@ -169,6 +175,11 @@ Show the version. - term `--help`: Show help information. +### Shell Options + +- term `--shell=\`: +Run a shell command for input or completion + ## math.help Show subcommand help information. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index aea0ee8dc..236f13cc0 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -130,34 +130,40 @@ Show help information. Print the quantiles of the values (TBD). ``` -math stats quantiles [] [] [] - [...] [--file=] [--directory=] [--shell=] - [--custom=] [--custom-deprecated=] [--version] - [--help] +math stats quantiles [...] [--file=] [--one-of-four=] + [--custom-arg=] [--custom-deprecated-arg=] + [--shell=] [--custom=] [--custom-deprecated=] + [--version] [--help] ``` ### Arguments -**one-of-four**: +**values**: +A group of floating-point values to operate on. -**custom-arg**: +### Custom Options -**custom-deprecated-arg**: +**--custom=\**: +Custom user-provided option with dynamic completion -**values**: -A group of floating-point values to operate on. +**--custom-deprecated=\**: +Deprecated custom option -### Options +### Input Options -**--file=\**: +**--one-of-four=\**: +Choose one of four predefined options -**--directory=\**: +**--custom-arg=\**: +Custom argument -**--shell=\**: +**--custom-deprecated-arg=\**: +Deprecated custom argument -**--custom=\**: +### Options -**--custom-deprecated=\**: +**--file=\**: +Input file or directory to process (default section). **--version**: Show the version. @@ -165,6 +171,11 @@ Show the version. **--help**: Show help information. +### Shell Options + +**--shell=\**: +Run a shell command for input or completion + ## math.help Show subcommand help information. diff --git a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc index 99288bd7f..16d32c1dc 100644 --- a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc +++ b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathMultiPageManual().mdoc @@ -226,12 +226,11 @@ and .Nd "Print the quantiles of the values (TBD)." .Sh SYNOPSIS .Nm -.Op Ar one-of-four -.Op Ar custom-arg -.Op Ar custom-deprecated-arg .Op Ar values... .Op Fl -file Ar file -.Op Fl -directory Ar directory +.Op Fl -one-of-four Ar one-of-four +.Op Fl -custom-arg Ar custom-arg +.Op Fl -custom-deprecated-arg Ar custom-deprecated-arg .Op Fl -shell Ar shell .Op Fl -custom Ar custom .Op Fl -custom-deprecated Ar custom-deprecated @@ -239,16 +238,22 @@ and .Op Fl -help .Sh DESCRIPTION .Bl -tag -width 6n -.It Ar one-of-four -.It Ar custom-arg -.It Ar custom-deprecated-arg .It Ar values... A group of floating-point values to operate on. .It Fl -file Ar file -.It Fl -directory Ar directory +Input file or directory to process (default section). +.It Fl -one-of-four Ar one-of-four +Choose one of four predefined options +.It Fl -custom-arg Ar custom-arg +Custom argument +.It Fl -custom-deprecated-arg Ar custom-deprecated-arg +Deprecated custom argument .It Fl -shell Ar shell +Run a shell command for input or completion .It Fl -custom Ar custom +Custom user-provided option with dynamic completion .It Fl -custom-deprecated Ar custom-deprecated +Deprecated custom option .It Fl -version Show the version. .It Fl h , -help diff --git a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc index 1aa384530..49923ff8e 100644 --- a/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc +++ b/Tests/ArgumentParserGenerateManualTests/Snapshots/testMathSinglePageManual().mdoc @@ -73,16 +73,22 @@ Show help information. .It Em quantiles Print the quantiles of the values (TBD). .Bl -tag -width 6n -.It Ar one-of-four -.It Ar custom-arg -.It Ar custom-deprecated-arg .It Ar values... A group of floating-point values to operate on. .It Fl -file Ar file -.It Fl -directory Ar directory +Input file or directory to process (default section). +.It Fl -one-of-four Ar one-of-four +Choose one of four predefined options +.It Fl -custom-arg Ar custom-arg +Custom argument +.It Fl -custom-deprecated-arg Ar custom-deprecated-arg +Deprecated custom argument .It Fl -shell Ar shell +Run a shell command for input or completion .It Fl -custom Ar custom +Custom user-provided option with dynamic completion .It Fl -custom-deprecated Ar custom-deprecated +Deprecated custom option .It Fl -version Show the version. .It Fl h , -help diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json index 01e3b89ee..85f9c6e3e 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathDumpHelp().json @@ -427,6 +427,43 @@ "abstract" : "Print the quantiles of the values (TBD).", "arguments" : [ { + "abstract" : "A group of floating-point values to operate on.", + "isOptional" : true, + "isRepeating" : true, + "kind" : "positional", + "parsingStrategy" : "default", + "shouldDisplay" : true, + "valueName" : "values" + }, + { + "abstract" : "Input file or directory to process (default section).", + "completionKind" : { + "file" : { + "extensions" : [ + "txt", + "md" + ] + } + }, + "isOptional" : true, + "isRepeating" : false, + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "file" + } + ], + "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "file" + }, + "shouldDisplay" : true, + "valueName" : "file" + }, + { + "abstract" : "Choose one of four predefined options", "completionKind" : { "list" : { "values" : [ @@ -439,12 +476,24 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "one-of-four" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "one-of-four" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "one-of-four" }, { + "abstract" : "Custom argument", "completionKind" : { "custom" : { @@ -452,12 +501,24 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "custom-arg" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "custom-arg" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "custom-arg" }, { + "abstract" : "Deprecated custom argument", "completionKind" : { "customDeprecated" : { @@ -465,20 +526,22 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "custom-deprecated-arg" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "custom-deprecated-arg" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "custom-deprecated-arg" }, - { - "abstract" : "A group of floating-point values to operate on.", - "isOptional" : true, - "isRepeating" : true, - "kind" : "positional", - "parsingStrategy" : "default", - "shouldDisplay" : true, - "valueName" : "values" - }, { "isOptional" : true, "isRepeating" : false, @@ -494,6 +557,7 @@ "kind" : "long", "name" : "test-success-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -512,6 +576,7 @@ "kind" : "long", "name" : "test-failure-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -530,6 +595,7 @@ "kind" : "long", "name" : "test-validation-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -548,59 +614,12 @@ "kind" : "long", "name" : "test-custom-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, { - "completionKind" : { - "file" : { - "extensions" : [ - "txt", - "md" - ] - } - }, - "isOptional" : true, - "isRepeating" : false, - "kind" : "option", - "names" : [ - { - "kind" : "long", - "name" : "file" - } - ], - "parsingStrategy" : "default", - "preferredName" : { - "kind" : "long", - "name" : "file" - }, - "shouldDisplay" : true, - "valueName" : "file" - }, - { - "completionKind" : { - "directory" : { - - } - }, - "isOptional" : true, - "isRepeating" : false, - "kind" : "option", - "names" : [ - { - "kind" : "long", - "name" : "directory" - } - ], - "parsingStrategy" : "default", - "preferredName" : { - "kind" : "long", - "name" : "directory" - }, - "shouldDisplay" : true, - "valueName" : "directory" - }, - { + "abstract" : "Run a shell command for input or completion", "completionKind" : { "shellCommand" : { "command" : "head -100 \/usr\/share\/dict\/words | tail -50" @@ -620,10 +639,12 @@ "kind" : "long", "name" : "shell" }, + "sectionTitle" : "Shell Options", "shouldDisplay" : true, "valueName" : "shell" }, { + "abstract" : "Custom user-provided option with dynamic completion", "completionKind" : { "custom" : { @@ -643,10 +664,12 @@ "kind" : "long", "name" : "custom" }, + "sectionTitle" : "Custom Options", "shouldDisplay" : true, "valueName" : "custom" }, { + "abstract" : "Deprecated custom option", "completionKind" : { "customDeprecated" : { @@ -666,6 +689,7 @@ "kind" : "long", "name" : "custom-deprecated" }, + "sectionTitle" : "Custom Options", "shouldDisplay" : true, "valueName" : "custom-deprecated" }, diff --git a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json index 725c51f63..782ff91ce 100644 --- a/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json +++ b/Tests/ArgumentParserUnitTests/Snapshots/testMathStatsDumpHelp().json @@ -210,6 +210,43 @@ "abstract" : "Print the quantiles of the values (TBD).", "arguments" : [ { + "abstract" : "A group of floating-point values to operate on.", + "isOptional" : true, + "isRepeating" : true, + "kind" : "positional", + "parsingStrategy" : "default", + "shouldDisplay" : true, + "valueName" : "values" + }, + { + "abstract" : "Input file or directory to process (default section).", + "completionKind" : { + "file" : { + "extensions" : [ + "txt", + "md" + ] + } + }, + "isOptional" : true, + "isRepeating" : false, + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "file" + } + ], + "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "file" + }, + "shouldDisplay" : true, + "valueName" : "file" + }, + { + "abstract" : "Choose one of four predefined options", "completionKind" : { "list" : { "values" : [ @@ -222,12 +259,24 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "one-of-four" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "one-of-four" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "one-of-four" }, { + "abstract" : "Custom argument", "completionKind" : { "custom" : { @@ -235,12 +284,24 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "custom-arg" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "custom-arg" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "custom-arg" }, { + "abstract" : "Deprecated custom argument", "completionKind" : { "customDeprecated" : { @@ -248,20 +309,22 @@ }, "isOptional" : true, "isRepeating" : false, - "kind" : "positional", + "kind" : "option", + "names" : [ + { + "kind" : "long", + "name" : "custom-deprecated-arg" + } + ], "parsingStrategy" : "default", + "preferredName" : { + "kind" : "long", + "name" : "custom-deprecated-arg" + }, + "sectionTitle" : "Input Options", "shouldDisplay" : true, "valueName" : "custom-deprecated-arg" }, - { - "abstract" : "A group of floating-point values to operate on.", - "isOptional" : true, - "isRepeating" : true, - "kind" : "positional", - "parsingStrategy" : "default", - "shouldDisplay" : true, - "valueName" : "values" - }, { "isOptional" : true, "isRepeating" : false, @@ -277,6 +340,7 @@ "kind" : "long", "name" : "test-success-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-success-exit-code" }, @@ -295,6 +359,7 @@ "kind" : "long", "name" : "test-failure-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-failure-exit-code" }, @@ -313,6 +378,7 @@ "kind" : "long", "name" : "test-validation-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-validation-exit-code" }, @@ -331,59 +397,12 @@ "kind" : "long", "name" : "test-custom-exit-code" }, + "sectionTitle" : "Hidden \/ Testing Options", "shouldDisplay" : false, "valueName" : "test-custom-exit-code" }, { - "completionKind" : { - "file" : { - "extensions" : [ - "txt", - "md" - ] - } - }, - "isOptional" : true, - "isRepeating" : false, - "kind" : "option", - "names" : [ - { - "kind" : "long", - "name" : "file" - } - ], - "parsingStrategy" : "default", - "preferredName" : { - "kind" : "long", - "name" : "file" - }, - "shouldDisplay" : true, - "valueName" : "file" - }, - { - "completionKind" : { - "directory" : { - - } - }, - "isOptional" : true, - "isRepeating" : false, - "kind" : "option", - "names" : [ - { - "kind" : "long", - "name" : "directory" - } - ], - "parsingStrategy" : "default", - "preferredName" : { - "kind" : "long", - "name" : "directory" - }, - "shouldDisplay" : true, - "valueName" : "directory" - }, - { + "abstract" : "Run a shell command for input or completion", "completionKind" : { "shellCommand" : { "command" : "head -100 \/usr\/share\/dict\/words | tail -50" @@ -403,10 +422,12 @@ "kind" : "long", "name" : "shell" }, + "sectionTitle" : "Shell Options", "shouldDisplay" : true, "valueName" : "shell" }, { + "abstract" : "Custom user-provided option with dynamic completion", "completionKind" : { "custom" : { @@ -426,10 +447,12 @@ "kind" : "long", "name" : "custom" }, + "sectionTitle" : "Custom Options", "shouldDisplay" : true, "valueName" : "custom" }, { + "abstract" : "Deprecated custom option", "completionKind" : { "customDeprecated" : { @@ -449,6 +472,7 @@ "kind" : "long", "name" : "custom-deprecated" }, + "sectionTitle" : "Custom Options", "shouldDisplay" : true, "valueName" : "custom-deprecated" }, From 2bc964f74bcdf290b8526276e763f50e037d6e88 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Sat, 4 Oct 2025 20:02:56 +0330 Subject: [PATCH 15/16] fix: align argument section sorting in documentation generation with help output --- .../Snapshots/testMathDoccReference().md | 26 ++++++------ .../Snapshots/testMathMarkdownReference().md | 26 ++++++------ .../Extensions/ArgumentParser+Markdown.swift | 42 ++++++++++++------- 3 files changed, 52 insertions(+), 42 deletions(-) diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 9c06d8378..5b45965be 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -145,14 +145,6 @@ math stats quantiles [...] [--file=] - term `values`: A group of floating-point values to operate on. -### Custom Options - -- term `--custom=\`: -Custom user-provided option with dynamic completion - -- term `--custom-deprecated=\`: -Deprecated custom option - ### Input Options - term `--one-of-four=\`: @@ -164,6 +156,19 @@ Custom argument - term `--custom-deprecated-arg=\`: Deprecated custom argument +### Shell Options + +- term `--shell=\`: +Run a shell command for input or completion + +### Custom Options + +- term `--custom=\`: +Custom user-provided option with dynamic completion + +- term `--custom-deprecated=\`: +Deprecated custom option + ### Options - term `--file=\`: @@ -175,11 +180,6 @@ Show the version. - term `--help`: Show help information. -### Shell Options - -- term `--shell=\`: -Run a shell command for input or completion - ## math.help Show subcommand help information. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index 236f13cc0..2de4c3875 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -141,14 +141,6 @@ math stats quantiles [...] [--file=] [--one-of-four=] **values**: A group of floating-point values to operate on. -### Custom Options - -**--custom=\**: -Custom user-provided option with dynamic completion - -**--custom-deprecated=\**: -Deprecated custom option - ### Input Options **--one-of-four=\**: @@ -160,6 +152,19 @@ Custom argument **--custom-deprecated-arg=\**: Deprecated custom argument +### Shell Options + +**--shell=\**: +Run a shell command for input or completion + +### Custom Options + +**--custom=\**: +Custom user-provided option with dynamic completion + +**--custom-deprecated=\**: +Deprecated custom option + ### Options **--file=\**: @@ -171,11 +176,6 @@ Show the version. **--help**: Show help information. -### Shell Options - -**--shell=\**: -Run a shell command for input or completion - ## math.help Show subcommand help information. diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 8223b7174..496db64d0 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -80,16 +80,26 @@ extension CommandInfoV0 { if let args = self.arguments { // Group arguments by sectionTitle // This is done to organize the arguments into categories (e.g., options, flags) - let groupedArgs = Dictionary( - grouping: args.filter { - $0.shouldDisplay - } - ) { $0.sectionTitleDefault } + let groupedArgs = Dictionary(grouping: args.filter { $0.shouldDisplay }) { $0.sectionTitleDefault } + + var customSectionTitles: [String] = [] + for arg in args { + if let title = arg.sectionTitle, + !title.isEmpty, + !customSectionTitles.contains(title) { + customSectionTitles.append(title) + } + } + + // Build final section order + let finalSectionOrder = ["Arguments"] + customSectionTitles + ["Options"] // 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 }) { + for section in finalSectionOrder { + guard let arguments = groupedArgs[section] else { continue } + // 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. @@ -256,16 +266,16 @@ extension ArgumentInfoV0 { } /// Returns the default section title for this argument. - fileprivate var sectionTitleDefault: String { - if let sectionTitle = self.sectionTitle { - return sectionTitle - } else { - switch self.kind { - case .positional: - return "Arguments" - case .option, .flag: - return "Options" - } + fileprivate var sectionTitleDefault: String { + if let sectionTitle = self.sectionTitle { + return sectionTitle + } else { + switch self.kind { + case .positional: + return "Arguments" + case .option, .flag: + return "Options" } } + } } From 4580ced54347711c1ddcff62b3044361eab37164 Mon Sep 17 00:00:00 2001 From: System Administrator Date: Sat, 4 Oct 2025 21:08:12 +0330 Subject: [PATCH 16/16] docs: update documentation generation comments for the refined solution --- .../Extensions/ArgumentParser+Markdown.swift | 47 ++++++++----------- 1 file changed, 20 insertions(+), 27 deletions(-) diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 496db64d0..b28af4956 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -78,10 +78,13 @@ extension CommandInfoV0 { } if let args = self.arguments { - // Group arguments by sectionTitle - // This is done to organize the arguments into categories (e.g., options, flags) + // Group the arguments by their section titles (either default or custom): + // - This organizes arguments into meaningful categories (e.g., "Arguments", "Options", or custom sections). + // - Using `sectionTitleDefault` ensures each argument falls into a valid section even if no custom title is provided. let groupedArgs = Dictionary(grouping: args.filter { $0.shouldDisplay }) { $0.sectionTitleDefault } + // Extract all custom section titles in the order they appear: + // - These titles are user defined and should appear between the default "Arguments" and "Options" sections. var customSectionTitles: [String] = [] for arg in args { if let title = arg.sectionTitle, @@ -91,30 +94,24 @@ extension CommandInfoV0 { } } - // Build final section order + // Build final section order to match the help output for consistency let finalSectionOrder = ["Arguments"] + customSectionTitles + ["Options"] - // 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. + // Iterate through the sections in the final defined order: + // - "Arguments" appear first, followed by any custom section titles, and "Options" last. + // - This order mirrors the help output, making the documentation intuitive and consistent. for section in finalSectionOrder { guard let arguments = groupedArgs[section] else { continue } - - // 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. + // improving the visual structure of the documentation. 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. - - - // 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. + // Format the argument name according to the documentation style: + // - For DocC, use `- term `name`:` so it is recognized as a term in a definition list. + // - For GitHub Markdown, use bold `**name**:` to visually emphasize the argument as a header. switch markdownStyle { case .docc: result += "- term `\(arg.identity())`:\n" @@ -122,28 +119,24 @@ extension CommandInfoV0 { result += "**\(arg.identity())**:\n" } + // Including the abstract provides a brief description of the argument's purpose. if let abstract = arg.abstract { result += "\(abstract)\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. + // ArgumentParser does not provide an abstract for the positional `subcommands` argument. + // Without this, the generated documentation would be missing a description, which could confuse users. + // Here we inject a default description for clarity in the documentation output. if arg.identity() == "subcommands" && arg.abstract == nil { result += "*Show help information.*\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. + // Discussion is added to provide further explanation on how the argument works. 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. + // The empty line improves the visual structure of the documentation. result += "\n" } }