Rustdoc: Change all 'optflag' arguments to 'optflagmulti' #73936
Conversation
|
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
added
the
S-waiting-on-review
|
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'. |
|
☔ The latest upstream changes (presumably #74117) made this pull request unmergeable. Please resolve the merge conflicts. |
Muirrum
added
S-waiting-on-author
ollie27
added
the
T-rustdoc
|
ping from triage |
|
@JohnCSimon there's not much point fixing the conflicts until @rust-lang/rustdoc agrees this is a change they want to make. |
jyn514
added
I-needs-decision
|
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
added
S-waiting-on-team
crlf0710
added
S-waiting-on-team
crlf0710
added
S-waiting-on-team
camelid
added
S-waiting-on-author
|
@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
removed
the
S-waiting-on-author
|
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 :) |
|
Yeah, I can take a look at getting this cleaned up this weekend. |
zachlute
force-pushed
the
rustdoc-optflagmulti
branch
from
b34d555 to
ab58928
Compare
|
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. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
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
force-pushed
the
rustdoc-optflagmulti
branch
from
275152a to
5302539
Compare
|
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. |
|
@bors r+ rollup squash |
|
@bors r+ rollup squash |
|
📌 Commit 0cc66c8 has been approved by |
bors
added
S-waiting-on-bors
|
@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. |
…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.
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
…mulacrum Document private items for rustfmt This is possible now that rust-lang#73936 has been merged.
Document private items for rustfmt This is possible now that rust-lang/rust#73936 has been merged.
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-itemsto binaries, because it's the only thing that makes sense there. Then some poor user comes along and adds--document-private-itemsto theirrustdocflags 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
rustdocflags 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 changerustdocto 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.