My first time committing to this repo so please let me know if I made any errors.

@alercah realized this has been marinating for awhile now

I'm no longer on the docs team, someone else should take a look. @Havvy or @Centril ?

@Centril Thanks for the review and comments! I have updated the pr as per your advice.

this is documented as a separate thing rather than being integrated with other parts of the reference. The text is also written in a guide-level manner rather than as reference text

Do you have a suggestion how I can improve this?

please make sure that all the examples actually compile on stable which they don't atm

Can I do a cargo test rather than checking each snippet of code? Used Rust playground to test all the examples. They should compile now.

Do you have a suggestion how I can improve this?

Before going into the examples, I would try to describe the set of rules, as a list, that give rise to your included examples (which are helpful).
E.g.

• &'foo Bar being well-formed implies Bar: 'foo

Sry it took so long to get back to this; been very busy. I had meant to do the improved version of the documentation but settling for getting something out.