Request expanded documentation on implementing `trait Header`

[coriolinus]

The impl Header for Dnt example is a good start, but it doesn't explain the actual semantics of the iterator-based design.

Example questions which would be nice to have answered in the documentation:

• Under what circumstances will the iterator provided to fn decode contain more than one value?
• If a decode implementation does not consume the provided iterator entirely, what happens to the remaining values?
  • Are they re-used to produce a new instance?
  • Are they just discarded?
• Under what circumstances is it reasonable to emit more than one value in fn encode?
• Are the encode and decode circumstances symmetrical?

[jocutajar]

Ahoj, how do I actually implement the trait?

struct CustomHeader;
const HEADER_NAME: HeaderName = HeaderName::from_static("custom-header");
impl Header for CustomHeader {
    fn name() -> &'static HeaderName {
        &HEADER_NAME
    }

    fn decode<'i, I>(values: &mut I) -> Result<Self, headers::Error>
    where
        Self: Sized,
        I: Iterator<Item = &'i HeaderValue>,
    {
        todo!()
    }

    fn encode<E: Extend<HeaderValue>>(&self, values: &mut E) {
        todo!()
    }
}

This does not compile, complaining of temporary in name() - which doesn't even make sense.