Enhance help texts of position args

[weihanglo]

What does this PR try to resolve?

Fixes #9707

In #9707, there is an assumption that people tend to run cargo run --help and expect it shows the help text of the binary to run. However, the two proposed solution there both may lead to a false positive. I personally don't feel like any of them is a solution we would consider.

How should we test and review this PR?

Run each command below and check its help text.

cargo run --help
cargo rustdoc --help
cargo rustc --help

[rustbot]

r? @ehuss

(rustbot has picked a reviewer for you, use r? to override)

[ehuss]

This looks good to me, but I'm going to r? @epage

[epage]

Agree that this is good on its own. Do we want to block closing out the issue on cargo help? If so, we could either block this PR on it or change the PR from saying "Fixes". I leave that to @weihanglo

[weihanglo]

I still think #9707 won't go anywhere, given we never knows if --help in your binary is really a help text or something else. Also, at the time the issue created, clap puts ARGS section at the bottom. It is now on the very top, which hugely improves the visibility. #9707 is generally “fixed” in terms of discovery I feel like.

[epage]

@bors r+

[bors]

📌 Commit e59ae78 has been approved by epage

It is now in the queue for this repository.

[bors]

⌛ Testing commit e59ae78 with merge 6e66ee8...

[bors]

☀️ Test successful - checks-actions
Approved by: epage
Pushing 6e66ee8 to master...

[pnkfelix]

I'm confused, and maybe I will go try to write my own pull request to resolve my own confusion. But before I go down that path, I want to understand the current situation.

However, the two proposed solution there both may lead to a false positive.

When you say the second suggestion may lead to a false positive, where the second suggestion in question is something covering the following two bullets:

• cargo run --help would also include a line suggesting that one might do cargo run -- --help
• cargo run --bin program --help would include a line suggesting cargo run --bin program -- --help

(where perhaps I should have emphasized "one might do" in the above).

I'm trying to understand the pro's and con's of suggesting the above to a user, who may not be familiar with the pattern of using -- to stop argument parser in other command line tools like ls.

Is the problem that concerns you that passing --help to the underlying binary could cause something other than a help message to be printed; for example, some destructive action could take place in response to the user issuing the command in question?

While I don't disagree that what you describe is possible in as a pathological scenario, I think it would solely arise as a pathological case. Someone who is willing to run a misunderstood (or worse yet, untrusted) binary via a blind invocation of cargo run is in for the same world of pain as someone willing to invoke cargo run -- --help.

---

Furthermore, ... maybe I misunderstand how cargo has evolved since I filed #9707, but ... the current help output for cargo run --help doesn't even mention the role of -- ...?

So, how is a user going to figure out from the current help output that what they need to do is pass -- --help?

At least the old help output used to include a mention [--] in the output, so one had a hint that it might be something one might need to use. But that [--] text no longer appears in the current output, perhaps due to underlying changes in clap, I do not know the details there.

[weihanglo]

Thank you for the reply! My bad I shouldn't rush on this change.

So, how is a user going to figure out from the current help output that what they need to do is pass -- --help?

The complete help is embedded in cargo help run today, which mentions the usage of --. It is unfortunately less visible though.

Is the problem that concerns you that passing --help to the underlying binary could cause something other than a help message to be printed; for example, some destructive action could take place in response to the user issuing the command in question?

Yes. From the angle of correctness, I am a bit reluctant to to give an answer that may not exist or not correct. For example, a user runs cargo run --bin x --target wasm-wasi --help. Should cargo suggest cargo run --bin x --target wasm32-wasi -- --help or cargo run --bin x -- --target wasm32-wasi --help, or even cargo run -- --bin x --target wasm32-wasi --help?

Another point is why only recommending --help but not other flags. But yep --help is more common and may be worth a line or two of suggestion.

From the technical aspect, the current help text is, iirc, static. There might be more works to make a dynamic suggestion happen.

To make this actionable, we could probably add back a concise version of the old message mentioning -- (current lives in cargo help run). I'll reopen the issue and thank you for still being aware of this issue!