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: allow moving methods from deref below trait impls via a new unstable command line argument #92273

Conversation

slightlyoutofphase
Copy link
Contributor

Basically, with this applied, running cargo rustdoc -- -Z unstable-options --show-deref-methods-last will generate docs with "Methods From Deref" as the last thing on the sidebar and main page body, as opposed to it coming right after "Methods".

I feel like this is a suitably unintrusive way of achieving the same thing that #83826 did before being reverted, as it does not change how docs are rendered at all in any scenario where the new flag is not explicitly passed.

@jyn514, since they originally provided feedback related to #83826.

@rust-highfive
Copy link
Collaborator

r? @CraftSpider

(rust-highfive has picked a reviewer for you, use r? to override)

@rustbot rustbot added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Dec 25, 2021
@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 25, 2021
@jyn514
Copy link
Member

jyn514 commented Dec 25, 2021

I'm on vacation the next month or so.

I'm a little hesitant to add more configuration to rustdoc; this seems sufficiently niche I don't think we should stabilize it and we already have far too many unstable flags.

@CraftSpider
Copy link
Contributor

I generally agree with that assessment as well, I don't think we need many more unstable flags

@slightlyoutofphase
Copy link
Contributor Author

slightlyoutofphase commented Dec 25, 2021

I don't think we should stabilize it

I did add it as an unstable one for that reason. I would not be concerned if it basically remained "perma-unstable" as various things in Rust often do.

Is there a better manner in which you suggest I might be able to re-implement what #83826 did for the two months or so it was merged? To be clear, the current state of things is that rustdoc behaves exactly as it did prior to that. Which is to say, your comment of:

#83826 was a response to #80653, which has since been reverted.

made on #85618 is not really true as far as I can tell. "Methods From Deref" are still currently rendered in their entirety directly after "Methods", no matter what.

@jyn514
Copy link
Member

jyn514 commented Dec 25, 2021

#83826 was a response to #80653, which has since been reverted.

We relanded the Deref PR recently: #90183

I did add it as an unstable one for that reason. I would not be concerned if it basically remained "perma-unstable" as various things in Rust often do.

This is exactly my point, rustdoc really don't need more perma-unstable flags.

I don't think #83826 was a bad change; maybe talk with @jsha about whether there's some compromise you can come to there, not sure whether I agree #85618 is actually a regression. Maybe we can put methods from the first deref before traits and methods from all other deref impls after?

@jyn514 jyn514 added the needs-fcp This change is insta-stable, so needs a completed FCP to proceed. label Dec 25, 2021
@jyn514 jyn514 changed the title rustdoc: re-implement #83826 via a new unstable command line argument rustdoc: allow moving methods from deref below trait impls via a new unstable command line argument Dec 25, 2021
@slightlyoutofphase
Copy link
Contributor Author

slightlyoutofphase commented Dec 25, 2021

Maybe we can put methods from the first deref before traits and methods from all other deref impls after?

Well, that unfortunately wouldn't help my motivating case for this PR (and for #83826) at all, which is having a struct that implements Deref with type Target = [T], resulting in the entire 2300+ line slice documentation page being inlined directly into the doc page for said struct as "Methods From Deref".

I agree that this rendering behavior does make sense in the specific case of std::alloc::Vec implementing Deref the same way as std docs are going to consistently be widely read by fresh newcomers to Rust, but for various reasons I don't think it makes sense in the case of my crate.

I certainly understand where you're coming from when you say "this is exactly my point, rustdoc really doesn't need more perma-unstable flags" also, but at the same time do think that a rustdoc with more opt-in unintrusive configurability is better than a rustdoc that simply has one unchangeable way of doing certain things designed with heavy bias towards "what's best for std" to the potential detriment of various other use cases.

Stuff like how rustdoc used to only expand the entries for locally custom-documented trait methods by default, but now blindly expands absolutely everything without differentiating between locally implemented / custom documented ones and externally "provided" / externally documented ones is another example of an IMO not-always-ideal way of doing things that I'd probably want to discuss making opt-in configurable in a separate issue or PR at some point, also.

@camelid
Copy link
Member

camelid commented Dec 27, 2021

Rustdoc has a lot of bugs and edge cases, and having many different ways to configure rustdoc doesn't help since it increases complexity. This seems like a fairly niche use case, so I'd also rather not add the flag, even if (or especially if) it's perma-unstable.

At some point, it might make sense to allow configuring rustdoc in a more uniform way, but having lots of one-off flags isn't the best way to do it IMO.

@slightlyoutofphase
Copy link
Contributor Author

I'd at least somewhat argue that the difference here is that this exact functionality was previously made the always-on default for rustdoc for about two months (something no one really appeared to have any problem with until one particular user did and opened an issue about it, not actually knowing it had been intentional initially IIRC).

@bors
Copy link
Contributor

bors commented May 21, 2022

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

@Mark-Simulacrum Mark-Simulacrum added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 24, 2022
@Dylan-DPC
Copy link
Member

Closing this based on the above discussion that there is no way forward for this pr to land. Thanks

@Dylan-DPC Dylan-DPC closed this Dec 20, 2022
@GuillaumeGomez
Copy link
Member

This PR has been open for a long time, and based on the discussion, it seems very unlikely that we will move forward with it. But in any case, thanks for working on this! Don't hesitate to come talk to us if you have more ideas.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs-fcp This change is insta-stable, so needs a completed FCP to proceed. S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). 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.

None yet

10 participants