Skip to content
This repository has been archived by the owner on Jan 1, 2022. It is now read-only.

App::about and Arg::help are inconsistent #16

Open
epage opened this issue Nov 18, 2021 · 0 comments
Open

App::about and Arg::help are inconsistent #16

epage opened this issue Nov 18, 2021 · 0 comments

Comments

@epage
Copy link
Owner

epage commented Nov 18, 2021

We have App::about, Arg::help and PossibleValue::help.

Should these be more consistent?

See a prior discussion for more context


Original Issue after #17

Transfered from clap-rs

When a user "knows" what they are looking for, they browse directly to it. As a user with clap3, when I'm looking to set the help description for an argument, I'm looking for help something in the Arg table of contents, but it wasn't there until beta.5 and its deprecated (Issue: clap-rs/clap#1823, PR: clap-rs/clap#1840). So in a way, clap-rs/clap#2718 has been helping but its of limited time until the next major release.

We have conflicting needs:

  • We want consistency within clap so its easier to move from one piece to another (the old Arg::help is analogous to App::about)
  • We want to be clear in our terms (does help refer to just a help description or the entire help, especially a problem in App)
  • We want to be discoverable
    • Which about hasn't been for me
    • In terms of past clap users, "do nothing" is discoverable
    • In terms of past structopt users, they don't care since they use doc comments :)
    • In terms of what people might be familiar with:
      • python's argparse's equivalent is App::description and Arg::help
      • golang's kong's equivalent is App::description and Arg::help
      • cpp's boost::program_option's equivalent is Arg::description
      • rust's gumpdrop's equivalent is Arg::help

The question is what do we prioritize and how should we resolve this?

I figured a discussion would be more appropriate rather than trying to lump this in with clap-rs/clap#2164

epage added a commit that referenced this issue Nov 18, 2021
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840

This is part of #16.  clap-rs/clap#1840 wasn't the right call but we
don't have time to make the decision now, so instead of having one
option and changing it in 4.0, this reverts back to clap2 behavior.
epage added a commit that referenced this issue Nov 18, 2021
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840

This is part of #16.  clap-rs/clap#1840 wasn't the right call but we
don't have time to make the decision now, so instead of having one
option and changing it in 4.0, this reverts back to clap2 behavior.
epage added a commit that referenced this issue Nov 18, 2021
This reverts commits 24cb8b1..d0abb37 from clap-rs/clap#1840

This is part of #16.  clap-rs/clap#1840 wasn't the right call but we
don't have time to make the decision now, so instead of having one
option and changing it in 4.0, this reverts back to clap2 behavior.
@epage epage changed the title Arg::about is unexpected, causing me to miss it when trying to look up the docs for what to tuse Arg::about is unexpected, causing me to miss it when trying to look up the docs for what to use Nov 29, 2021
@epage epage changed the title Arg::about is unexpected, causing me to miss it when trying to look up the docs for what to use App::about and Arg::help are inconsistent Dec 3, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant