apple / apple/swift-argument-parser

Mutually exclusive `EnumerableFlag` & `RawRepresentable` flags aren't documented as such in command help, possibly elsewhere

Open
#831 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
3.8k
Forks
411
Avg merge
7d 14h
Merged PRs (30d)
15

Description

Mutually exclusive `EnumerableFlag` & `RawRepresentable` flags aren't documented as such in command help.

They're just listed as independent flags.

Maybe they're also listed as independent elsewhere, e.g., generated man page, markdown, etc.

Maybe other types of mutually exclusive flags, options, arguments, whatever also suffer from this problem.

Also, the default flag is output in an overly verbose, confusing way:

```text
--a 1 (default: --a)
```

Which probably should be:

```text
--a 1 (default)
```

**ArgumentParser version:**

main

**Swift version:**

swift-driver version: 1.127.14.1 Apple Swift version 6.2.1 (swiftlang-6.2.1.4.8 clang-1700.4.4.1)
Target: arm64-apple-macosx26.0

### Checklist

- [x] If possible, I've reproduced the issue using the `main` branch of this package
- [x] I've searched for [existing GitHub issues](https://github.com/apple/swift-argument-parser/issues)

### Steps to Reproduce

```swift
internal import ArgumentParser

struct C: ParsableCommand {
static let configuration = CommandConfiguration(
abstract: "C"
)

@Flag(help: "group text")
private var e = E.a

func run() {
print(e)
}
}

private enum E: String, EnumerableFlag {
case a
case b
case c

static func help(for e: Self) -> ArgumentHelp? {
switch e {
case .a:
"1"
case .b:
"2"
case .c:
"3"
}
}
}
```

### Expected behavior

```console
$ c help
OVERVIEW: C

USAGE: cmd c [--a | --b | --c]

OPTIONS:
--a 1 (default)
--b 2
--c 3
-h, --help Show help information.
```

Or, maybe segment the mutually exclusive options together (output could be different):

```console
$ c help
OVERVIEW: C

USAGE: cmd c [--a | --b | --c]

OPTIONS:
group text (mutually exclusive):
--a 1 (default)
--b 2
--c 3

OTHER OPTIONS:
-h, --help Show help information.
```

### Actual behavior

```console
$ c help
OVERVIEW: C

USAGE: cmd c [--a] [--b] [--c]

OPTIONS:
--a 1 (default: --a)
--b 2
--c 3

-h, --help Show help information.
```

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the issue with the provided Swift `ParsableCommand` and `EnumerableFlag` example, then trace the help-generation entry point that produces the usage and option text. Check whether generated man pages or Markdown are affected as suggested. Done means mutually exclusive flags are represented accurately in help output and the default is shown without the redundant flag name.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.