Private supertrait pattern

[dtolnay]

This pattern is a way to retain the ability to add/remove/modify methods of a public trait without breaking compatibility. Example from byteorder: BurntSushi/byteorder#69.

[dtolnay]

Relevant discussion in the context of Hyper: hyperium/hyper#1194

[dtolnay]

Added in e7d7202.

[matklad]

@dtolnay curious, why we put #[doc(hidden)] on the methods of the public trait, if we can just add these methods to the private counterpart? That is, something like this should work?

I don't think that it matters much in practice, but doc(hidden) methods are still visible, and might cause ambiguous method calls in theory....

EDIT: nvm, methods of private supertraits are visible if you import the public trait: https://play.rust-lang.org/?gist=4cb854858e5cae10a25a40680d6a687c&version=stable&mode=debug&edition=2015