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

Author: Chamepp

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

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md

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

Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md

@@ -6,26 +6,34 @@
 count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
 ```
 
-**input-file:**
-
-*A file to count lines in. If omitted, counts the lines of stdin.*
+## Arguments
 
+**`input-file`**
 
-**--prefix=\<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=\<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>...] 
 ```
 
-**subcommands:**
-
-
-
-
+## Arguments
 
+**`subcommands`**

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,76 +30,78 @@ Print the sum of the values.
 math add [--hex-output] [<values>...] [--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.
 
 ```
 math multiply [--hex-output] [<values>...] [--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.
 
 ```
 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,109 +110,105 @@ Print the average of the values.
 math stats average [--kind=<kind>] [<values>...] [--version] [--help]
 ```
 
-**--kind=\<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=\<kind\>`**
 
-### math.stats.stdev
+*The kind of average to provide.*### math.stats.stdev
 
 Print the standard deviation of the values.
 
 ```
 math stats stdev [<values>...] [--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).
 
 ```
 math stats quantiles [<one-of-four>] [<custom-arg>] [<values>...]     [--file=<file>] [--directory=<directory>] [--shell=<shell>] [--custom=<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=\<file\>:**
 
+**`values`**
 
-**--directory=\<directory\>:**
+*A group of floating-point values to operate on.*
 
 
-**--shell=\<shell\>:**
+## Flags
 
+**`--version`**
 
-**--custom=\<custom\>:**
+*Show the version.*
 
 
-**--version:**
+**`--help`**
 
-*Show the version.*
+*Show help information.*
 
 
-**--help:**
+## Optionals
 
-*Show help information.*
+**`--file=\<file\>`**
 
 
+**`--directory=\<directory\>`**
 
 
+**`--shell=\<shell\>`**
 
 
-## math.help
+**`--custom=\<custom\>`**## math.help
 
 Show subcommand help information.
 
 ```
 math help [<subcommands>...] 
 ```
 
-**subcommands:**
-
-
-
-
+## Arguments
 
+**`subcommands`**