Conform to the recommended pattern for sealed traits

[dtolnay]

The header module contains these two traits:

pub trait Header: HeaderClone + GetType + Send + Sync {
    fn header_name() -> &'static str where Self: Sized;
    fn parse_header(raw: &Raw) -> ::Result<Self> where Self: Sized;
    fn fmt_header(&self, f: &mut Formatter) -> fmt::Result;
}

#[doc(hidden)]
pub trait HeaderClone {
    fn clone_box(&self) -> Box<Header + Send + Sync>;
}

As discussed in the libz blitz evaluation, we would like a recognizable pattern for sealed traits that are impossible to implement outside of the current crate. We would like this pattern to be independent of whether certain functionality on a trait is a doc(hidden) implementation detail.

As such, we would like to:

• Move clone_box (which is an implementation detail not relevant to users of hyper) from HeaderClone into a doc(hidden) method in Header
• Rename the now-empty HeaderClone to Sealed
• Mention in the documentation of Header that this trait is sealed and designed to be implemented only within the hyper codebase

[seanmonstar]

There may have been a misunderstanding of the usage of this trait. The Header (and HeaderFormat) trait is meant to be implemented by users outside of hyper. The HeaderClone trait is an implementation detail that is only used inside hyper, which guarantees that T: Header is also T: Clone, and since the headers are put into a boxed trait object, Box<Header>, that a clone_box() method exists so that hyper can clone them internally.

The HeaderClone trait has a blanket impl inside hyper for all T: Header + Clone...

[dtolnay]

You are right. I misunderstood these traits.

To tease this apart:

• There is a trait Header that users are meant to implement. They are also free to call the Header trait methods if they want.
• There is a trait HeaderClone that users are not meant to implement, nor call its trait methods.

How would you feel about these changes?

• Add an empty private supertrait Sealed to HeaderClone.
• Put doc(hidden) on the clone_box method.
• Publicly expose HeaderClone.

I like this because now Header has all public supertraits so it is clear that you can implement it. Previously Header had a private supertrait which suggests that you will not be able to implement it.

Also now rustdoc can show the HeaderClone for T: Header + Clone impl, so users can tell from rustdoc what types they are allowed to implement Header for. Previously they would have to dive through some hidden types to find this out.

[seanmonstar]

This has been done, and and is viewable in https://docs.rs/hyper/0.10.12.