Improve documentation examples and streamline architecture support

[phip1611]

• Split backend into mmio.rs (always) and pio.rs (x86-only) to localize cfg usage at module boundaries
• Switched to #[cfg(any(x86..., doc))] so rustdoc includes all items across architectures
• Enabled doc_cfg on docs.rs for proper platform-specific annotations
• No functional changes; purely improves structure, maintainability, and documentation

[phip1611]

Hints for reviewers: it's working

[phip1611]

Yikes this was more painful than anticipated but I've learned something about cross-architecture rustdoc builds :D

[mkroening]

Splitting into modules definitely makes sense. 👍

The second commit does not seem to do what it says. 🤔

• Switched to #[cfg(any(x86..., doc))] so rustdoc includes all items across architectures

Why is this useful? I have never seen a crate do this. Instead, you can switch the platform on docs.rs.

[phip1611]

The second commit does not seem to do what it says. 🤔

Do you refer to an old commit? 🤔 I'm not sure which one you are talking about.

Instead, you can switch the platform on docs.rs.

I did not know this 😁 interesting

Why is this useful? I have never seen a crate do this.

TL;DR: I have a feeling that a documentation should include everything (with markers for feature gates).

This is I think my first library crate with platform specific API, I think. I have no idea what the standard is. To me, it feels natural that the documentation includes everything if one reads them. e.g., if one build the documentation on their macbook and opens it, the documentation should tell the developer how they can do stuff on a x86 PC, for example.

I think this is quite useful and the necessary changes to the codebase are fairly small.

What do you think? Do you see any risk?

[mkroening]

The second commit does not seem to do what it says. 🤔

Do you refer to an old commit? 🤔 I'm not sure which one you are talking about.

I mean this one: 1f47a91

To me, it feels natural that the documentation includes everything if one reads them. e.g., if one build the documentation on their macbook and opens it, the documentation should tell the developer how they can do stuff on a x86 PC, for example.

I think this is quite useful and the necessary changes to the codebase are fairly small.

What do you think? Do you see any risk?

I think the default is to enable all features for building docs, but not all target-dependent options such as OS or architecture. If a aarch64-apple-darwin user like me is interested in x86 docs, I would use cargo doc --target x86_64-unknown-none. I would personally be confused by cargo doc --target aarch64-apple-darwin containing x86-only items.

Take, for example, libc. They enable a plethora of targets for building in docs.rs. I would be confused if I was interested in what API is available on macOS but also saw every other OS when searching or reading, even if it had the yellow boxes.

If you prefer it like that, it should be fine; I was just confused at first. :D

[phip1611]

Thanks for the heads-up - I simply didn't know 😁

I think I'm in favor of keeping it the current way.

1. It is not that much overhead
2. Without it, linking to [`Uart16550::new_port()`] in the docs is a pain with #[cfg_attr(..., doc = "...")]