rustdoc: separate trait docs from default impl docs?

[sgtatham]

The documentation for a trait and its methods often includes advice, suggestions, or a list of options for the developer implementing the trait. For example, the docs for PartialEq::ne() mention that implementors shouldn't override the default version of ne() without a good reason.

This is useful advice if I'm reading the PartialEq documentation itself, as a developer figuring out how to implement it on one of my own types. But if I'm reading the documentation for a type which has implemented PartialEq, say in somebody else's crate, and I see the same text saying "implementors shouldn't override this without a good reason", it's very out of place. Firstly, it's directing the advice at the wrong person: I'm not in control of whether the crate author overrode ne(). And secondly, it's complaining about a thing that didn't even happen – very likely the reason that default method documentation is being shown to me is because the crate author sensibly didn't override the default ne().

It would be useful if there was a way to separate the "advice to implementors" part of the trait documentation from the text about what each trait method does. That way, in the context of an existing implementation of the trait, this kind of out-of-place text wouldn't appear at all.

(Original version of this thought on Mastodon, although there it forms a combined rant with a separate complaint that implementors often don't override the default docs, e.g. saying which implementation choice they did make out of the options, or explaining what addition semantically means for their type. Here I'm only discussing point 2 of the combined complaint. In the Mastodon thread @GuillaumeGomez suggested I raise this ticket for discussion.)

[llogiq]

Duplicate of #139855.

[GuillaumeGomez]

Closing since it's a duplicate but thanks for opening the issue in any case. :)