rustdoc: allow moving methods from deref below trait impls via a new unstable command line argument

[slightlyoutofphase]

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]

r? @CraftSpider

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

[jyn514]

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]

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

[slightlyoutofphase]

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]

#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?

[slightlyoutofphase]

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]

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]

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]

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

[Dylan-DPC]

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

[GuillaumeGomez]

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.