diff --git a/Examples/math/Math.swift b/Examples/math/Math.swift index e98234d0b..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 dca1d8336..96cd32c12 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 269a72e54..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 6e0ab5fbc..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/testColorDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md index 7e9ea67f2..a5360d913 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md @@ -6,22 +6,18 @@ color --fav= [--second=] [--help] ``` -- term **--fav=\**: +### Options -*Your favorite color.* - - -- term **--second=\**: - -*Your second favorite color.* +- term `--fav=\`: +Your favorite color. +- term `--second=\`: +Your second favorite color. This is optional. -- term **--help**: - -*Show help information.* - +- term `--help`: +Show help information. ## color.help @@ -31,9 +27,7 @@ Show subcommand help information. color help [...] ``` -- term **subcommands**: - - - - +### Arguments +- term `subcommands`: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md index 6d16c6da3..6e9d8460e 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md @@ -6,22 +6,18 @@ color --fav= [--second=] [--help] ``` -**--fav=\:** +### Options -*Your favorite color.* - - -**--second=\:** - -*Your second favorite color.* +**--fav=\**: +Your favorite color. +**--second=\**: +Your second favorite color. This is optional. -**--help:** - -*Show help information.* - +**--help**: +Show help information. ## color.help @@ -31,9 +27,7 @@ Show subcommand help information. color help [...] ``` -**subcommands:** - - - - +### Arguments +**subcommands**: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md index 48d93d7cb..b4cc3de45 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md @@ -7,25 +7,21 @@ count-lines [] [--prefix=] [--verbose] [--help] ``` -- term **input-file**: +### Arguments -*A file to count lines in. If omitted, counts the lines of stdin.* +- 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. -*Only count lines with this prefix.* - - -- term **--verbose**: - -*Include extra information in the output.* - - -- term **--help**: - -*Show help information.* +- term `--verbose`: +Include extra information in the output. +- term `--help`: +Show help information. ## count-lines.help @@ -35,9 +31,7 @@ Show subcommand help information. count-lines help [...] ``` -- term **subcommands**: - - - - +### Arguments +- term `subcommands`: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md index 619e81d1c..c26cfa4f0 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesMarkdownReference().md @@ -6,25 +6,21 @@ count-lines [] [--prefix=] [--verbose] [--help] ``` -**input-file:** +### Arguments -*A file to count lines in. If omitted, counts the lines of stdin.* +**input-file**: +A file to count lines in. If omitted, counts the lines of stdin. +### Options -**--prefix=\:** +**--prefix=\**: +Only count lines with this prefix. -*Only count lines with this prefix.* - - -**--verbose:** - -*Include extra information in the output.* - - -**--help:** - -*Show help information.* +**--verbose**: +Include extra information in the output. +**--help**: +Show help information. ## count-lines.help @@ -34,9 +30,7 @@ Show subcommand help information. count-lines help [...] ``` -**subcommands:** - - - - +### Arguments +**subcommands**: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md index 847a76462..5b45965be 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md @@ -8,15 +8,13 @@ A utility for performing maths. math [--version] [--help] ``` -- term **--version**: +### Options -*Show the version.* - - -- term **--help**: - -*Show help information.* +- term `--version`: +Show the version. +- term `--help`: +Show help information. ## math.add @@ -26,27 +24,21 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -- term **--hex-output**: - -*Use hexadecimal notation for the result.* - - -- term **values**: - -*A group of integers to operate on.* +### Arguments +- term `values`: +A group of integers to operate on. -- term **--version**: - -*Show the version.* - - -- term **--help**: - -*Show help information.* +### Options +- term `--hex-output`: +Use hexadecimal notation for the result. +- term `--version`: +Show the version. +- term `--help`: +Show help information. ## math.multiply @@ -57,27 +49,21 @@ math multiply [--hex-output] [...] [--version] [--help] ``` -- term **--hex-output**: - -*Use hexadecimal notation for the result.* - - -- term **values**: +### Arguments -*A group of integers to operate on.* +- term `values`: +A group of integers to operate on. +### Options -- term **--version**: - -*Show the version.* - - -- term **--help**: - -*Show help information.* - +- term `--hex-output`: +Use hexadecimal notation for the result. +- term `--version`: +Show the version. +- term `--help`: +Show help information. ## math.stats @@ -87,15 +73,13 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -- term **--version**: - -*Show the version.* - +### Options -- term **--help**: - -*Show help information.* +- term `--version`: +Show the version. +- term `--help`: +Show help information. ### math.stats.average @@ -106,27 +90,21 @@ math stats average [--kind=] [...] [--version] [--help] ``` -- term **--kind=\**: - -*The kind of average to provide.* - +### Arguments -- term **values**: +- term `values`: +A group of floating-point values to operate on. -*A group of floating-point values to operate on.* - - -- term **--version**: - -*Show the version.* - - -- term **--help**: - -*Show help information.* +### Options +- term `--kind=\`: +The kind of average to provide. +- term `--version`: +Show the version. +- term `--help`: +Show help information. ### math.stats.stdev @@ -136,78 +114,71 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -- term **values**: - -*A group of floating-point values to operate on.* - - -- term **--version**: - -*Show the version.* - +### Arguments -- term **--help**: - -*Show help information.* +- 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 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] ``` -- term **one-of-four**: - - -- term **custom-arg**: - - -- term **custom-deprecated-arg**: - - -- term **values**: +### Arguments -*A group of floating-point values to operate on.* +- term `values`: +A group of floating-point values to operate on. +### Input Options -- term **--file=\**: +- term `--one-of-four=\`: +Choose one of four predefined options +- term `--custom-arg=\`: +Custom argument -- term **--directory=\**: +- term `--custom-deprecated-arg=\`: +Deprecated custom argument +### Shell Options -- term **--shell=\**: +- term `--shell=\`: +Run a shell command for input or completion +### Custom Options -- term **--custom=\**: - - -- term **--custom-deprecated=\**: - - -- term **--version**: - -*Show the version.* - - -- term **--help**: - -*Show help information.* +- term `--custom=\`: +Custom user-provided option with dynamic completion +- term `--custom-deprecated=\`: +Deprecated custom option +### Options +- term `--file=\`: +Input file or directory to process (default section). +- term `--version`: +Show the version. +- term `--help`: +Show help information. ## math.help @@ -217,14 +188,12 @@ Show subcommand help information. math help [...] [--version] ``` -- term **subcommands**: - - -- term **--version**: - -*Show the version.* - - +### Arguments +- term `subcommands`: +*Show help information.* +### Options +- term `--version`: +Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md index 00997feb5..2de4c3875 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathMarkdownReference().md @@ -8,15 +8,13 @@ A utility for performing maths. math [--version] [--help] ``` -**--version:** +### Options -*Show the version.* - - -**--help:** - -*Show help information.* +**--version**: +Show the version. +**--help**: +Show help information. ## math.add @@ -26,27 +24,21 @@ Print the sum of the values. math add [--hex-output] [...] [--version] [--help] ``` -**--hex-output:** - -*Use hexadecimal notation for the result.* - - -**values:** - -*A group of integers to operate on.* +### Arguments +**values**: +A group of integers to operate on. -**--version:** - -*Show the version.* - - -**--help:** - -*Show help information.* +### Options +**--hex-output**: +Use hexadecimal notation for the result. +**--version**: +Show the version. +**--help**: +Show help information. ## math.multiply @@ -56,27 +48,21 @@ Print the product of the values. math multiply [--hex-output] [...] [--version] [--help] ``` -**--hex-output:** - -*Use hexadecimal notation for the result.* - - -**values:** +### Arguments -*A group of integers to operate on.* +**values**: +A group of integers to operate on. +### Options -**--version:** - -*Show the version.* - - -**--help:** - -*Show help information.* - +**--hex-output**: +Use hexadecimal notation for the result. +**--version**: +Show the version. +**--help**: +Show help information. ## math.stats @@ -86,15 +72,13 @@ Calculate descriptive statistics. math stats [--version] [--help] ``` -**--version:** - -*Show the version.* - +### Options -**--help:** - -*Show help information.* +**--version**: +Show the version. +**--help**: +Show help information. ### math.stats.average @@ -104,27 +88,21 @@ 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. -*A group of floating-point values to operate on.* - - -**--version:** - -*Show the version.* - - -**--help:** - -*Show help information.* +### Options +**--kind=\**: +The kind of average to provide. +**--version**: +Show the version. +**--help**: +Show help information. ### math.stats.stdev @@ -134,76 +112,69 @@ Print the standard deviation of the values. math stats stdev [...] [--version] [--help] ``` -**values:** - -*A group of floating-point values to operate on.* - - -**--version:** - -*Show the version.* - +### Arguments -**--help:** - -*Show help information.* +**values**: +A group of floating-point values to operate on. +### Options +**--version**: +Show the version. +**--help**: +Show help information. ### math.stats.quantiles 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] ``` -**one-of-four:** - - -**custom-arg:** - - -**custom-deprecated-arg:** - - -**values:** +### Arguments -*A group of floating-point values to operate on.* +**values**: +A group of floating-point values to operate on. +### Input Options -**--file=\:** +**--one-of-four=\**: +Choose one of four predefined options +**--custom-arg=\**: +Custom argument -**--directory=\:** +**--custom-deprecated-arg=\**: +Deprecated custom argument +### Shell Options -**--shell=\:** +**--shell=\**: +Run a shell command for input or completion +### Custom Options -**--custom=\:** - - -**--custom-deprecated=\:** - - -**--version:** - -*Show the version.* - - -**--help:** - -*Show help information.* +**--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. +**--help**: +Show help information. ## math.help @@ -213,14 +184,12 @@ Show subcommand help information. math help [...] [--version] ``` -**subcommands:** - - -**--version:** - -*Show the version.* - - +### Arguments +**subcommands**: +*Show help information.* +### Options +**--version**: +Show the version. diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md index 60f104d78..af0790985 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md @@ -7,25 +7,21 @@ repeat [--count=] [--include-counter] [--help] ``` -- term **--count=\**: +### Arguments -*How many times to repeat 'phrase'.* +- term `phrase`: +The phrase to repeat. +### Options -- term **--include-counter**: +- term `--count=\`: +How many times to repeat 'phrase'. -*Include a counter with each repetition.* - - -- term **phrase**: - -*The phrase to repeat.* - - -- term **--help**: - -*Show help information.* +- term `--include-counter`: +Include a counter with each repetition. +- term `--help`: +Show help information. ## repeat.help @@ -35,9 +31,7 @@ Show subcommand help information. repeat help [...] ``` -- term **subcommands**: - - - - +### Arguments +- term `subcommands`: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md index f3ab3e621..341e9082d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatMarkdownReference().md @@ -6,25 +6,21 @@ repeat [--count=] [--include-counter] [--help] ``` -**--count=\:** +### Arguments -*How many times to repeat 'phrase'.* +**phrase**: +The phrase to repeat. +### Options -**--include-counter:** +**--count=\**: +How many times to repeat 'phrase'. -*Include a counter with each repetition.* - - -**phrase:** - -*The phrase to repeat.* - - -**--help:** - -*Show help information.* +**--include-counter**: +Include a counter with each repetition. +**--help**: +Show help information. ## repeat.help @@ -34,9 +30,7 @@ Show subcommand help information. repeat help [...] ``` -**subcommands:** - - - - +### Arguments +**subcommands**: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md index 306fae0d0..f4453ea1d 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md @@ -7,32 +7,24 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -- term **--times=\**: +### Options -*Rolls the dice times.* - - -- term **--sides=\**: - -*Rolls an -sided dice.* +- 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 `--seed=\`: +A seed to use for repeatable random generation. +- term `--verbose`: +Show all roll results. -- term **--verbose**: - -*Show all roll results.* - - -- term **--help**: - -*Show help information.* - +- term `--help`: +Show help information. ## roll.help @@ -42,9 +34,7 @@ Show subcommand help information. roll help [...] ``` -- term **subcommands**: - - - - +### Arguments +- term `subcommands`: +*Show help information.* diff --git a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md index 8e0bd3874..043c6b5b9 100644 --- a/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md +++ b/Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollMarkdownReference().md @@ -6,32 +6,24 @@ roll [--times=] [--sides=] [--seed=] [--verbose] [--help] ``` -**--times=\:** +### Options -*Rolls the dice times.* - - -**--sides=\:** - -*Rolls an -sided dice.* +**--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.* +**--seed=\**: +A seed to use for repeatable random generation. +**--verbose**: +Show all roll results. -**--verbose:** - -*Show all roll results.* - - -**--help:** - -*Show help information.* - +**--help**: +Show help information. ## roll.help @@ -41,9 +33,7 @@ Show subcommand help information. roll help [...] ``` -**subcommands:** - - - - +### Arguments +**subcommands**: +*Show 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 badff7811..1a6e75be5 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 0a1e95164..590cefc30 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" }, diff --git a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift index 170e89704..b28af4956 100644 --- a/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift +++ b/Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift @@ -78,25 +78,67 @@ extension CommandInfoV0 { } if let args = self.arguments { + // 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 { - guard arg.shouldDisplay else { - continue - } + if let title = arg.sectionTitle, + !title.isEmpty, + !customSectionTitles.contains(title) { + customSectionTitles.append(title) + } + } - switch markdownStyle { - case .docc: - result += "- term **\(arg.identity())**:\n\n" - case .github: - result += "**\(arg.identity()):**\n\n" - } + // Build final section order to match the help output for consistency + let finalSectionOrder = ["Arguments"] + customSectionTitles + ["Options"] - if let abstract = arg.abstract { - result += "*\(abstract)*\n\n" - } - if let discussion = arg.discussion { - result += discussion + "\n\n" + // 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 } + + // Adding section titles as Markdown headers helps separate sections in the documentation, + // improving the visual structure of the documentation. + result += "### \(section)\n\n" + + // Iterating through each argument allows us to add details for each argument under its respective section. + for arg in arguments { + // 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" + case .github: + result += "**\(arg.identity())**:\n" + } + + // Including the abstract provides a brief description of the argument's purpose. + if let abstract = arg.abstract { + result += "\(abstract)\n" + } + + // 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" + } + + // Discussion is added to provide further explanation on how the argument works. + if let discussion = arg.discussion { + result += discussion + "\n\n" + } + + // The empty line improves the visual structure of the documentation. + result += "\n" } - result += "\n" } } @@ -106,6 +148,11 @@ extension CommandInfoV0 { path + [self.commandName], markdownStyle: markdownStyle) + "\n\n" } + // 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 } @@ -140,6 +187,7 @@ extension CommandInfoV0 { } } + extension ArgumentInfoV0 { /// Returns a string that describes the use of the argument. /// @@ -209,4 +257,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" + } + } + } } diff --git a/Tools/generate-docc-reference/GenerateDoccReference.swift b/Tools/generate-docc-reference/GenerateDoccReference.swift index 922ded496..9453df3d6 100644 --- a/Tools/generate-docc-reference/GenerateDoccReference.swift +++ b/Tools/generate-docc-reference/GenerateDoccReference.swift @@ -28,8 +28,7 @@ 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)" } @@ -111,12 +110,13 @@ struct GenerateDoccReference: ParsableCommand { } let toolInfo: ToolInfoV0 + do { toolInfo = try JSONDecoder().decode(ToolInfoV0.self, from: data) } catch { throw GenerateDoccReferenceError.unableToParseToolOutput(error: error) } - + do { if self.outputDirectory == "-" { try self.generatePages(