rust rustdoc: it should be possible to leave "Methods From Deref" empty, as was previously the default behaviour - Rust

For example, I would much rather have the documentation for my crate Staticvec look as it did here, as opposed to pulling in the docs for every single slice method as it does now.

Edit: Some additional thoughts: - even if this isn't possible for some reason, it would almost certainly be better to have the crate-native "Trait Implementations" section appear before the "Methods From Deref" section does, since "Trait Implementations" will pretty much always be describing things that are unique to the crate being documented and so actually directly relevant - a good idea might also be to have the "Methods From Deref" header amount to a clickable link that redirects to the actual primary docs for whatever is being derefed to in any case where it is being left empty, if that is still possible

Asked Oct 19 '21 20:10
avatar slightlyoutofphase
slightlyoutofphase

6 Answer:

even if this isn't possible for some reason, it would almost certainly be better to have the crate-native "Trait Implementations" section appear before the "Methods From Deref" section does, since "Trait Implementations" will pretty much always be describing things that are unique to the crate being documented and so actually directly relevant

:+1: I like this idea.

a good idea might also be to have the "Methods From Deref" header amount to a clickable link that redirects to the actual primary docs for whatever is being derefed to in any case where it is being left empty, if that is still possible

Hmm, I'm a little concerned the methods will be harder to find that way. We get a lot of complaints that the "Trait Implementations" section is hard to read because you have to click on the name of the trait to see what methods are available.

1
Answered Mar 30 '21 at 15:04
avatar  of jyn514
jyn514

Hmm, I'm a little concerned the methods will be harder to find that way. We get a lot of complaints that the "Trait Implementations" section is hard to read because you have to click on the name of the trait to see what methods are available.

Yeah, that makes sense. Honestly just showing Trait Implementations before Methods From Deref in any case where both exist would likely pretty much cover the kind of thing I was mostly concerned about by itself anyways.

1
Answered Mar 31 '21 at 18:53
avatar  of slightlyoutofphase
slightlyoutofphase

Got busy with some other stuff, but I've now opened a PR that make those changes, which do accomplish what you thought they would.

1
Answered Apr 03 '21 at 20:44
avatar  of slightlyoutofphase
slightlyoutofphase

Are there any details on when precisely this changed, also? I've noticed that even though the auto-generated docs on docs.rs previously left the "Methods From Deref" section empty for user-submitted crates, it was seemingly always filled out for stuff like the official libstd docs for Vec, so presumably there has always been some kind of way of controlling rustdoc's behaviour in this regard, unless I'm missing something.

1
Answered Mar 21 '21 at 00:57
avatar  of slightlyoutofphase
slightlyoutofphase

Are there any details on when precisely this changed, also?

Yes, it was changed intentionally in https://github.com/rust-lang/rust/pull/80653 and mentioned in the release notes: https://github.com/rust-lang/rust/blob/master/RELEASES.md#rustdoc.

I've noticed that even though the auto-generated docs on docs.rs previously left the "Methods From Deref" section empty for user-submitted crates, it was seemingly always filled out for stuff like the official libstd docs for Vec, so presumably there has always been some kind of way of controlling rustdoc's behaviour in this regard, unless I'm missing something.

Vec derefs directly to slice - maybe the user crates you're talking about always deref to Vec?

1
Answered Mar 30 '21 at 15:02
avatar  of jyn514
jyn514

Honestly just showing Trait Implementations before Methods From Deref in any case where both exist would likely pretty much cover the kind of thing I was mostly concerned about by itself anyways.

Are you interested in making a PR for that? I think it would be as simple as moving https://github.com/rust-lang/rust/blob/a5029ac0ab372aec515db2e718da6d7787f3d122/src/librustdoc/html/render/mod.rs#L1934-L1940 after https://github.com/rust-lang/rust/blob/a5029ac0ab372aec515db2e718da6d7787f3d122/src/librustdoc/html/render/mod.rs#L2001-L2007 :)

1
Answered Mar 31 '21 at 18:59
avatar  of jyn514
jyn514