Document using peripheral drivers in generic contexts

[bugadani]

It's not obvious to users what/how they should use to create functions that accept any peripheral singleton of a particular type (e.g. any UART, any SPI). We internally use the Instance traits but we don't intend to stabilize those just yet, so users "can't" use them. We should document the intended solution for both the simple "function takes any peripheral" case, as well as "function takes any peripheral and a compatible DMA channel or other associated resource" case.

[MabezDev]

Won't the Instance traits still be public? We'll need them for our constructors, so I think end users can still use the Instance trait bounds. Regardless though, as you mentioned we should document a few cases demonstrating this.

[MabezDev]

Where do you think this content belongs? In the book, or in the API docs somewhere?

[bugadani]

We should maybe have a "Concepts" chapter in the book for this and related how-tos.

[bjoernQ]

We should maybe have a "Concepts" chapter in the book for this and related how-tos.

Sounds good but on the other hand explaining things in module level / crate level docs would limit the number of documents a user needs to look at? e.g. the stdlib explains a few advanced concepts in module level docs (e.g. https://doc.rust-lang.org/std/ptr/index.html#provenance )