doc: add detailed doc for enum descriptions.

Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md

@@ -37,7 +37,7 @@ OPTIONS:
 
 ### Customizing Help for Arguments
 
-For more control over the help text, pass an ``ArgumentHelp`` instance instead of a string literal. The `ArgumentHelp` type can include an abstract (which is what the string literal becomes), a discussion, a value name to use in the usage string, and a visibility level for that argument.
+For more control over the help text, pass an `ArgumentHelp` instance instead of a string literal. The `ArgumentHelp` type can include an abstract (which is what the string literal becomes), a discussion, a value name to use in the usage string, and a visibility level for that argument.
 
 Here's the same command with some extra customization:
 
@@ -76,7 +76,7 @@ OPTIONS:
 
 ### Enumerating Possible Values
 
-When an argument or option has a fixed set of possible values, listing these values in the help screen can simplify use of your tool. You can customize the displayed set of values for custom ``ExpressibleByArgument`` types by implementing ``ExpressibleByArgument/allValueStrings``. Despite the name, ``ExpressibleByArgument/allValueStrings`` does _not_ need to be an exhaustive list of possible values.
+When an argument or option has a fixed set of possible values, listing these values in the help screen can simplify use of your tool. You can customize the displayed set of values for custom `ExpressibleByArgument` types by implementing `ExpressibleByArgument/allValueStrings`. Despite the name, `ExpressibleByArgument/allValueStrings` does _not_ need to be an exhaustive list of possible values.
 
 ```swift
 enum Fruit: String, ExpressibleByArgument {
@@ -93,7 +93,7 @@ enum Fruit: String, ExpressibleByArgument {
 struct FruitStore: ParsableCommand {
     @Argument(help: "The fruit to purchase")
     var fruit: Fruit
-  
+
     @Option(help: "The number of fruit to purchase")
     var quantity: Int = 1
 }
@@ -115,7 +115,7 @@ OPTIONS:
 
 #### Deriving Possible Values
 
-ExpressibleByArgument types that conform to `CaseIterable` do not need to manually specify ``ExpressibleByArgument/allValueStrings``. Instead, a list of possible values is derived from the type's cases, as in this updated example:
+ExpressibleByArgument types that conform to `CaseIterable` do not need to manually specify `ExpressibleByArgument/allValueStrings`. Instead, a list of possible values is derived from the type's cases, as in this updated example:
 
 ```swift
 enum Fruit: String, CaseIterable, ExpressibleByArgument {
@@ -128,7 +128,7 @@ enum Fruit: String, CaseIterable, ExpressibleByArgument {
 struct FruitStore: ParsableCommand {
     @Argument(help: "The fruit to purchase")
     var fruit: Fruit
-  
+
     @Option(help: "The number of fruit to purchase")
     var quantity: Int = 1
 }
@@ -148,7 +148,114 @@ OPTIONS:
   -h, --help              Show help information.
 ```
 
-For an ``ExpressibleByArgument`` and `CaseIterable` type with many cases, you may still want to implement ``ExpressibleByArgument/allValueStrings`` to avoid an overly long list of values appearing in the help screen. For these types it is recommended to include the most common possible values.
+For an `ExpressibleByArgument` and `CaseIterable` type with many cases, you may still want to implement `ExpressibleByArgument/allValueStrings` to avoid an overly long list of values appearing in the help screen. For these types it is recommended to include the most common possible values.
+
+## Providing Descriptions for Individual Enum Values
+
+When your argument or option uses an enum type, you can provide detailed descriptions for each enum value that will appear in the help screen. This is especially useful when the enum cases represent complex concepts that benefit from explanation.
+
+### Basic Enum Value Descriptions
+
+To provide descriptions for individual enum values, implement a custom `defaultValueDescription` property for each case. The ArgumentParser will automatically detect when descriptions differ from the enum's string representation and display them in an enumerated format.
+
+```swift
+enum OutputFormat: String, CaseIterable, ExpressibleByArgument {
+    case json
+    case yaml
+    case xml
+    case csv
+
+    var defaultValueDescription: String {
+        switch self {
+        case .json:
+            return "JavaScript Object Notation format"
+        case .yaml:
+            return "YAML Ain't Markup Language format"
+        case .xml:
+            return "eXtensible Markup Language format"
+        case .csv:
+            return "Comma-Separated Values format"
+        }
+    }
+}
+
+struct DataExporter: ParsableCommand {
+    @Option(help: "Select output format")
+    var format: OutputFormat = .json
+}
+```
+
+This produces help output with detailed descriptions for each enum value:
+
+```
+USAGE: data-exporter [--format <format>]
+
+OPTIONS:
+  --format <format>       Select output format (default: json)
+        json              - JavaScript Object Notation format
+        yaml              - YAML Ain't Markup Language format
+        xml               - eXtensible Markup Language format
+        csv               - Comma-Separated Values format
+  -h, --help              Show help information.
+```
+
+### Array Options with Enum Descriptions
+
+The same enum value descriptions work seamlessly with array options, allowing users to understand each possible value when multiple selections are allowed:
+
+```swift
+struct DataExporter: ParsableCommand {
+    @Option(help: "Output formats to generate")
+    var formats: [OutputFormat] = [.json]
+}
+```
+
+The help screen displays descriptions for each format option:
+
+```
+USAGE: data-exporter [--formats <formats> ...]
+
+OPTIONS:
+  --formats <formats>     Output formats to generate (default: json)
+        json              - JavaScript Object Notation format
+        yaml              - YAML Ain't Markup Language format
+        xml               - eXtensible Markup Language format
+        csv               - Comma-Separated Values format
+  -h, --help              Show help information.
+```
+
+### Working with Raw Values
+
+For enums with custom raw values, the descriptions work with the raw value representation. Here's the same `OutputFormat` enum with custom raw values:
+
+```swift
+enum OutputFormat: String, CaseIterable, ExpressibleByArgument {
+    case json = "json"
+    case yaml = "yml"  
+    case xml = "xml"
+    case csv = "csv"
+
+    var defaultValueDescription: String {
+        switch self {
+        case .json:
+            return "JavaScript Object Notation format"
+        case .yaml:
+            return "YAML Ain't Markup Language format"
+        case .xml:
+            return "eXtensible Markup Language format"
+        case .csv:
+            return "Comma-Separated Values format"
+        }
+    }
+}
+
+struct DataExporter: ParsableCommand {
+    @Option(help: "Select output format")
+    var format: OutputFormat = .json
+}
+```
+
+In this example, users would specify `--format yml` to get YAML output, but the help screen still shows the descriptive text.
 
 ### Controlling Argument Visibility
 
@@ -164,7 +271,7 @@ struct Example: ParsableCommand {
 }
 ```
 
-The `--verbose` flag is only visible in the extended help screen. The `--use-legacy-format` stays hidden even in the extended help screen, due to its `.private` visibility. 
+The `--verbose` flag is only visible in the extended help screen. The `--use-legacy-format` stays hidden even in the extended help screen, due to its `.private` visibility.
 
 ```
 % example --help
@@ -181,7 +288,7 @@ OPTIONS:
   -h, --help              Show help information.
 ```
 
-Alternatively, you can group multiple arguments, options, and flags together as part of a ``ParsableArguments`` type, and set the visibility when including them as an `@OptionGroup` property.
+Alternatively, you can group multiple arguments, options, and flags together as part of a `ParsableArguments` type, and set the visibility when including them as an `@OptionGroup` property.
 
 ```swift
 struct ExperimentalFlags: ParsableArguments {
@@ -220,7 +327,7 @@ OPTIONS:
 
 ### Grouping Arguments in the Help Screen
 
-When you provide a title in an `@OptionGroup` declaration, that type's  properties are grouped together under your title in the help screen. For example, this command bundles similar arguments together under a  "Build Options" title:
+When you provide a title in an `@OptionGroup` declaration, that type's properties are grouped together under your title in the help screen. For example, this command bundles similar arguments together under a "Build Options" title:
 
 ```swift
 struct BuildOptions: ParsableArguments {