Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rustdoc: Change all 'optflag' arguments to 'optflagmulti' #73936

Merged
merged 2 commits into from
Jul 11, 2021

Conversation

zachlute
Copy link
Contributor

@zachlute zachlute commented Jul 1, 2020

Because specifying these flags multiple times will never be discernibly different in functionality from specifying them a single time, there is no reason to fail and report an error to the user.

This might be a slightly controversial change. it's tough to say, but it's hard to imagine a case where somebody was depending on this behavior, and doing this seem actively better for the user.

This originally came up in discussion of a fix for Cargo #8373, in Cargo PR #8422.

The issue is that Cargo will automatically add things like --document-private-items to binaries, because it's the only thing that makes sense there. Then some poor user comes along and adds --document-private-items to their rustdoc flags for the project and suddenly they're getting errors for specifying a flag twice and need to track down which targets to actually add it to without getting duplicates for reasons they won't understand without deep understanding of Cargo behavior.

We're apparently hesitant to inspect rustdoc flags provided by the user directly in Cargo, because they're supposed to be opaque, so looking to see if it's already provided before adding it is evidently a non-starter. In trying to resolve that, one suggestion I came up with was to just change rustdoc to support passing the flag multiple times, because the user's intent should be clear and it's not really an error, so maybe this is a case of 'be permissive in what you accept'.

This PR is an attempt to do that in a straightforward manner for purposes of discussion.

@rust-highfive
Copy link
Collaborator

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @GuillaumeGomez (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 1, 2020
@jyn514
Copy link
Member

jyn514 commented Jul 1, 2020

I think this change is reasonable but it should also give a warning if the option was passed multiple times. That way people aren't confused that 'my private binary function shows up even without --document-private-items'.

@bors
Copy link
Contributor

bors commented Jul 7, 2020

☔ The latest upstream changes (presumably #74117) made this pull request unmergeable. Please resolve the merge conflicts.

@Muirrum Muirrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 24, 2020
@ollie27 ollie27 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Jul 24, 2020
@JohnCSimon
Copy link
Member

ping from triage
@zachlute - can you please address the merge conflicts?
thanks

@jyn514
Copy link
Member

jyn514 commented Aug 11, 2020

@JohnCSimon there's not much point fixing the conflicts until @rust-lang/rustdoc agrees this is a change they want to make.

@jyn514 jyn514 closed this Aug 11, 2020
@jyn514 jyn514 reopened this Aug 11, 2020
@jyn514 jyn514 added I-needs-decision Issue: In need of a decision. S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Aug 11, 2020
@zachlute
Copy link
Contributor Author

Yeah, happy to clean this up and get it into mergeable shape provided there's consensus it would actually be merged. It was kind of a drive-by as a result of trying to fix a Cargo bug, so I'm hesitant to put much more work into it without some buy-in. :)

@crlf0710 crlf0710 added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Aug 28, 2020
@crlf0710 crlf0710 added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Sep 18, 2020
@crlf0710 crlf0710 added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Oct 8, 2020
@camelid camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Oct 23, 2020
@JohnCSimon
Copy link
Member

Ping from triage:
@zachlute - can you please update the status of this PR?
cc: @jyn514

@jyn514
Copy link
Member

jyn514 commented Nov 9, 2020

@JohnCSimon same status as last time, this is waiting on team and there's not much point fixing the conflicts until then.

@Dylan-DPC-zz Dylan-DPC-zz removed the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Nov 10, 2020
@jyn514
Copy link
Member

jyn514 commented Jul 2, 2021

I agree we should accept this silently (without warning). @zachlute are you up for implementing that? Sorry for the extended delay, I think this just needs a rebase :)

@jyn514 jyn514 removed the I-needs-decision Issue: In need of a decision. label Jul 2, 2021
@zachlute
Copy link
Contributor Author

zachlute commented Jul 2, 2021

Yeah, I can take a look at getting this cleaned up this weekend.

@zachlute
Copy link
Contributor Author

Ugh, as usual, any time I need to do anything complicated with git I screw it up. Somehow in rebasing this I've ended up with a bunch of other random changes included in the list of changes in this PR? Sigh. I'll just create a new branch with the change, which is what I always end up doing anyway because git seems designed to make me look dumb regularly.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

Because specifying these flags multiple times will never be discernibly different in functionality from specifying them a single time, there is no reason to fail and report an error to the user.
@zachlute
Copy link
Contributor Author

Apologies for all the jumping around here. I had a smarter friend help me do this again and I believe the change should now be correct.

@jyn514
Copy link
Member

jyn514 commented Jul 10, 2021

@bors r+ rollup squash

@jyn514 jyn514 closed this Jul 10, 2021
@jyn514 jyn514 reopened this Jul 10, 2021
@jyn514
Copy link
Member

jyn514 commented Jul 10, 2021

@bors r+ rollup squash

@bors
Copy link
Contributor

bors commented Jul 10, 2021

📌 Commit 0cc66c8 has been approved by jyn514

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 10, 2021
@ehuss
Copy link
Contributor

ehuss commented Jul 10, 2021

@jyn514 Just FYI, the bors squash option is somewhat broken in that it strips authorship of the git commit (rust-lang/homu#136) and can prevent GitHub from realizing the PR is merged. Not sure if most people care, but I think it should probably be avoided until it is fixed. I also haven't looked, but I'm uncertain how it interacts with rollups.

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Jul 11, 2021
…n514

Rustdoc: Change all 'optflag' arguments to 'optflagmulti'

Because specifying these flags multiple times will never be discernibly different in functionality from specifying them a single time, there is no reason to fail and report an error to the user.

This might be a slightly controversial change. it's tough to say, but it's hard to imagine a case where somebody was depending on this behavior, and doing this seem actively better for the user.

This originally came up in discussion of a fix for  [Cargo rust-lang#8373](rust-lang/cargo#8373), in [Cargo PR rust-lang#8422](rust-lang/cargo#8422).

The issue is that Cargo will automatically add things like `--document-private-items` to binaries, because it's the only thing that makes sense there. Then some poor user comes along and adds `--document-private-items` to their `rustdoc` flags for the project and suddenly they're getting errors for specifying a flag twice and need to track down which targets to actually add it to without getting duplicates for reasons they won't understand without deep understanding of Cargo behavior.

We're apparently hesitant to inspect `rustdoc` flags provided by the user directly in Cargo, because they're supposed to be opaque, so looking to see if it's already provided before adding it is evidently a non-starter. In trying to resolve that, one suggestion I came up with was to just change `rustdoc` to support passing the flag multiple times, because the user's intent should be clear and it's not *really* an error, so maybe this is a case of 'be permissive in what you accept'.

This PR is an attempt to do that in a straightforward manner for purposes of discussion.
bors added a commit to rust-lang-ci/rust that referenced this pull request Jul 11, 2021
Rollup of 8 pull requests

Successful merges:

 - rust-lang#73936 (Rustdoc: Change all 'optflag' arguments to 'optflagmulti')
 - rust-lang#86926 (Update regex crates)
 - rust-lang#86951 ([docs] Clarify behaviour of f64 and f32::sqrt when argument is negative zero)
 - rust-lang#87031 (Update reference.md)
 - rust-lang#87037 (cleanup(rustdoc): remove unused function getObjectNameById)
 - rust-lang#87045 (Fix tracking issue for `bool_to_option`)
 - rust-lang#87049 (Account for `submodules = false` in config.toml when updating LLVM submodule)
 - rust-lang#87061 (Do not suggest adding a semicolon after `?`)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 25dda36 into rust-lang:master Jul 11, 2021
@rustbot rustbot added this to the 1.55.0 milestone Jul 11, 2021
bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 17, 2021
…mulacrum

Document private items for rustfmt

This is possible now that rust-lang#73936 has been merged.
calebcartwright pushed a commit to calebcartwright/rustfmt that referenced this pull request Oct 20, 2021
Document private items for rustfmt

This is possible now that rust-lang/rust#73936 has been merged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.