Overview of pointer types and related traits

[birkenfeld]

When diving deeper into the PyO3 docs, I'm always flattened by the sheer number of smart pointer types and related traits. I get that most of them are necessary, and some of them may be remnants that are on the way out, but it's still overwhelming, especially once you start playing tetris with those types, trying to get the result you need. The guide doesn't help in that regard.

I propose (and volunteer to draft, as far as I understand it) a table-like list of those traits, their approximate meaning, and when to use them.

It can be located in the guide, or in the API docs, as you prefer. But wherever it is, it should be linked to from every mentioned type's API docs, and the explanations should be made consistent.

[davidhewitt]

Thanks. I think something like this is probably best suited for the guide. Probably with a link to it also from the module documentation frontpage.

If during your audit you have any proposals for simplifying the trait/type taxonomy, we'd be very willing to hear them.

(Also see #687 which discusses one possible simplification.)