Write design doc for yoke

[Manishearth]

Part of #1474

This should be a good step for making it possible for others to understand this crate. I also plan to use parts of the "high level design" section of this as crate-level docs for this crate.

I'll be writing a similar doc for ZeroVec as well (#1475)

cc @echeran @nordzilla who I think expressed interest in understanding this crate better and potentially helping out with patches/reviews (though this crate is not changing much anymore)

[Manishearth]

@sffc I'd really prefer to call this "lifetime erasure", "self referential borrowing" is a huge field in Rust with many crates already. When explaining what yoke does to other rustaceans I've found "lifetime erasure" to be quite clear since it makes a clear analogy with "type erasure" (dyn)

[sffc]

I see lifetime erasure as being a means to an end. Yoke applies its lifetime erasure to a very narrow use case, which is self-references. I took another stab at the headline which mentions both things.

[Manishearth]

I still kinda feel like the relationship is inverted: the point of Yoke is lifetime erasure, and it accomplishes that by self referential borrowing. There's no way lifetime erasure can work without self referential borrowing as well.

[Manishearth]

Ultimately, to me, "self referential borrowing" does not tell me much because it covers so many things. "lifetime erasure" tells me exactly what this crate is useful for: I want to turn a compile time lifetime into an erased runtime one.

[Manishearth]

Like, to be clear, by "lifetime erasure" I'm not talking about the fact that yoke replaces lifetimes with static as a means to an end.

I'm making an analogy against type erasure: turn a compile time construct into a runtime one.

[Manishearth]

Let me write it out in the doc

[sffc]

I applied my feedback directly in your branch. Feel free to counter-edit my suggestions.