Print supported values in synopses, when practical

apple / swift-argument-parser

Straightforward, type-safe argument parsing for Swift

Apache License 2.0

3.3k stars 311 forks source link

Print supported values in synopses, when practical #620

Open numist opened 5 months ago

numist commented 5 months ago

This PR adds support for conditionally expanding argument and subcommand synopses to reflect supported values when there are multiple values and their combined length is not overly onerous.

To use an example from math, this PR changes the current:

USAGE: math <subcommand>

USAGE: math <add|multiply|stats>

But does not change the output for commands with a single subcommand or commands with very long subcommands.

Checklist

[x] I've added at least one test that validates that my change is working, if appropriate
[x] I've followed the code style of the rest of the project
[x] I've read the Contribution Guidelines
[x] I've updated the documentation if necessary

rauhul commented 5 months ago

I'm not fully convinced this is a readability improvement over the valid options appearing below.

IMO the synopsis should be succinct and the options below should contain the details.

numist commented 5 months ago

Reasonable! What got me started down this path was the idea that it should be possible to write a correct invocation of a command after the briefest possible glance at its usage, which is necessarily at odds with brevity (and introduces repetition).

Another possibility is that ArgumentParser could expand values only when the options are not explained ("short help", in this reply to Nate)

natecook1000 commented 2 months ago

Coming back to this – what would you think about reducing the scope, so that this adds the supported values for options (e.g. [--ripeness <under|perfect|over>]) but doesn't replace the placeholder name for arguments or subcommands? The option value change seems purely additive, but we'll need to discuss the other two a bit more. Thanks!

numist commented 1 month ago

Done!