(MODULES-9428) Clarify composite namevar edgecases and add examples

[DavidS]

I'll come back to this after contributor summit.

[DavidS]

I've found a few more tickets that fold into the composite namevars issue that I'd like to bundle into this fix:

• https://tickets.puppetlabs.com/browse/PDK-1219 - purging multi-namevar resources fails when the provider does not return a title
• https://tickets.puppetlabs.com/browse/PDK-1220 - document that multi-namevar types should return a title from get
• https://tickets.puppetlabs.com/browse/PDK-1221 - add consistency checks for title attribute on multi-namevar providers

PDK-1220 is already covered in this text, the others need a bit more consideration.

---

against my usual preferences in this repo, I've rebased and munged the commits on this change as far as it went to separate the editorial and the content changes.

[DavidS]

@Lavinia-Dan @da-ar this is now in a shape to review. Note that the commits are broken up into distinct chunks that should help reduce clutter during reviewing.

[DavidS]

Ok, I think this wraps it up. The implementation is available at https://github.com/puppetlabs/puppet-resource_api/pull/174 and there don't seem to be further comments here.