Swift ArgumentParser: why do top-level arguments clobber subcommand arguments?

[robert.ryan]

@nnnnnnnn

We definitely don't want the default instead of your own implementation, but the default is nice for commands that have commands that aren't end points, but have one or more subcommands (or nested subcommands) that do the actual work. In those cases, those intermediate subcommands don't require a run() implementation and the default behavior of printing help (that includes their subcommands) is a nice simplification.

First, thanks for your time in engaging in this thread. Your input is always great.

Second, would you be open to a PR that clarified the documentation a bit? I’m thinking of a “note” that warns developers that if they get “usage” text rather than executing run, that this is either because either:

• They failed to provide a run implementation;
• There were some non-optional options defined, but were not provided at the command line (or should the documentation just say “don’t do that!”; the whole idea of an “option” that is required feels like an anti-pattern; lol); or
• They are using ParsableCommand with an asynchronous run implementation.

FWIW, we have already added a comment on that last point, but I wonder if further clarification might be warranted.

And if you are open to such a PR, are there other scenarios that might result in the unintentional “usage” message that you’d like to add to the list?

I think that Options declared in a command with subcommands can cause issues might reveal some other weird edge cases.