Arg::about is unexpected, causing me to miss it when trying to look up the docs for what to tuse

[epage]

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: #1823, PR: #1840). So in a way, #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 #2164

[pksunkara]

Semantically, describing an arg is a description but not help since we use description to build the help message. I don't mind renaming the about functions and variables into description if you really think we need to.

about hasn't been discoverable for me

I would say it's an issue for docs.rs because they don't search the description of the items IIRC.

[epage]

I was hoping to get some people from the issue involved so we can make sure we aren't just doubling down on the problem but improving things.

[pksunkara]

They haven't been active in clap for a long time. Do you want to wait after creating an issue? I am afraid we might lose track of this in discussions.

[epage]

In thinking about creating an issue (regardless of solution, as long as it involves a rename), if we can't resolve it before 3.0 comes out, we end up causing churn for people as they switch back and forth between different options.

As I've thought about this more, I lean towards reverting back to the original naming. At best, its what people prefer and they are happier. At worst, this buys us more time to evaluate this.

[pksunkara]

If that's help, then I am against it because of the reasons given above. I am heavily leaning towards description and let's focus on resolving this before 3.0

[epage]

We have enough on our plate for 3.0, we should not be taking on the bike shedding of this name. Saying "not yet" and deferring the investigation to 3.x with removal of any deprecated functions in 4.0 would be a big help for the 3.0 release.

[epage]

@CreepySkeleton and @Dylan-DPC any thoughts?