Update the Adaptation docs to be more concrete.

[jamadden]

This should help provide better motivating use cases compared to the what the docs called the "silly" example of converting one number to another.

Examples inspired by https://glyph.twistedmatrix.com/2021/03/interfaces-and-protocols.html

Also some minor typo fixes and updates to comments. (One of which is for zopefoundation/zope.component#53.)

[jensens]

I often explain adaption with the abstract factory design pattern. At least for those who learned about design patterns this simplifies understanding a lot.

[jamadden]

Agreed, that can be a good way to explain it.

I'm not sure that's the appropriate approach for this particular piece documentation though, because it's, well, abstract 😄

The original was trying to work through some concrete examples, with the intent of showing how things work and how you can use them. But upon re-reading it as a result of asking glyph to link to it, I found that the "concrete" examples, well, weren't (converting 0 into 42? Why would I want to do that?). I wanted to improve that and make the material more engaging so that hopefully people can more easily imagine how they might use it in their projects. Using points was the first example that came to mind (and it seemed pretty good because there are many representations for the same thing, but they all work slightly differently), but if there's a better one I'd be happy to make adjustments.

[icemac]

LGTM.

[jamadden]

Thank you for the reviews and comments.

[jensens]

Do not get me wrong, your example makes it way easier to understand. Thanks! It was just an idea....