Enumerate the circumstances in which private in public is acceptable

[dtolnay]

In serde_json::value::Index there is a private supertrait to seal the trait and allow it to evolve as needed. This is an acceptable use.

In reqwest::RedirectPolicy::custom the RedirectAttempt from the function signature is private, which forces the user to express their redirect policy as a closure. There is no way they can factor it out into a function. This seems unnecessary.

[dtolnay]

Another case to consider here:

impl From<InternalFrom<Error>> for Error

The InternalFrom type is private but this is an implementation of a public trait so it is part of the public API. Maybe this is fine but then rustdoc should not show this impl.

[dtolnay]

I would like to propose that if a public trait has a private super trait, then:

• The private supertrait must be named Sealed.
• The private supertrait must have no methods.
• The private supertrait must have no supertraits of its own.

The name Sealed means users can get used to this pattern and won't be frustrated by not being able to see something like HeaderClone in the documentation.

The other two points do not affect the API so I guess they don't belong in API guidelines, but they make this confusing pattern easier to see and understand when reading code.

[dtolnay]

Public trait implementations that are not intended to be available to users, like impl From<InternalFrom<Error>> for Error, should have #[doc(hidden)].

[dtolnay]

This is sufficiently covered by C-SEALED and C-HIDDEN.