[GenerateDocCReference] Improve filtering and categorization of arguments in documentation with sectionTitle

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)
       }
     }

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 [<one-of-four>] [<custom-arg>] [<custom-deprecated-arg>] [<values> ...] [--file <file>] [--directory <directory>] [--shell <shell>] [--custom <custom>] [--custom-deprecated <custom-deprecated>]
+      USAGE: math stats quantiles [<values> ...] [--file <file>] [--one-of-four <one-of-four>] [--custom-arg <custom-arg>] [--custom-deprecated-arg <custom-deprecated-arg>] [--shell <shell>] [--custom <custom>] [--custom-deprecated <custom-deprecated>]
 
       ARGUMENTS:
-        <one-of-four>
-        <custom-arg>
-        <custom-deprecated-arg>
         <values>                A group of floating-point values to operate on.
 
-      OPTIONS:
-        --file <file>
-        --directory <directory>
-        --shell <shell>
-        --custom <custom>
+      INPUT OPTIONS:
+        --one-of-four <one-of-four>
+                                Choose one of four predefined options
+        --custom-arg <custom-arg>
+                                Custom argument
+        --custom-deprecated-arg <custom-deprecated-arg>
+                                Deprecated custom argument
+
+      SHELL OPTIONS:
+        --shell <shell>         Run a shell command for input or completion
+
+      CUSTOM OPTIONS:
+        --custom <custom>       Custom user-provided option with dynamic completion
         --custom-deprecated <custom-deprecated>
+                                Deprecated custom option
+
+      OPTIONS:
+        --file <file>           Input file or directory to process (default section).
         --version               Show the version.
         -h, --help              Show help information.
 

Tests/ArgumentParserExampleTests/Snapshots/testMathBashCompletionScript().bash

@@ -233,17 +233,25 @@ _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
     '--file')
         __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() {

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.'

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.]'
     )

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md

@@ -6,22 +6,18 @@
 color --fav=<fav> [--second=<second>] [--help]
 ```
 
-- term **--fav=\<fav\>**:
+### Options
 
-*Your favorite color.*
-
-
-- term **--second=\<second\>**:
-
-*Your second favorite color.*
+- term `--fav=\<fav\>`:
+Your favorite color.
 
+- term `--second=\<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 [<subcommands>...]
 ```
 
-- term **subcommands**:
-
-
-
-
+### Arguments
 
+- term `subcommands`:
+*Show help information.*

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorMarkdownReference().md

@@ -6,22 +6,18 @@
 color --fav=<fav> [--second=<second>] [--help]
 ```
 
-**--fav=\<fav\>:**
+### Options
 
-*Your favorite color.*
-
-
-**--second=\<second\>:**
-
-*Your second favorite color.*
+**--fav=\<fav\>**:
+Your favorite color.
 
+**--second=\<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>...]
 ```
 
-**subcommands:**
-
-
-
-
+### Arguments
 
+**subcommands**:
+*Show help information.*