Hi! This crate looks exciting and at @Dirbaio's suggestion I'm trying to evaluate it for an application. I was about a week away from doing this myself out of frustration with other options, so I'm delighted to see you've already put so much work into it.

I ran into a series of problems trying to evaluate it, and I thought you might want to hear about them / see if there are improvements possible.

The first place I went was https://docs.rs/stm32-metapac/latest/stm32_metapac/ . (Normally when someone suggests "have a look at crate X," docs.rs/X is a good place to start.) I was greeted with a long list of modules with no introductory documentation, no information about what stm32 chip I'm looking at / the docs were generated for, etc. (One advantage of the stm32-rs project's "we're going to squat on every possible stm32 crate name" approach is that it interacts better with docs.rs, since I can pull up the g0 docs or the h7 docs specifically -- even if their use of features means I sometimes can't see the right variant.)

So, I poked down into a few modules for peripherals I'm familiar with, like flash and rcc, and the situation became no clearer. (I would have at this point written it off as a half-finished crate, were it not for Dario's endorsement.)

Having had docs.rs issues myself, I figured this was a difficult documentation generation problem, so I came to the repo looking for links to generated docs in the readme, without success. Even the README is focused on being a repository for stm32 data (which is useful! and thank you for organizing it) but gives me no sense of

• What crate I would pull into an application to make use of the result -- is stm32-metapac right, or a placeholder? Or are there device crates?
• How you're using Cargo features (e.g. looks like you're doing a single crate for all possible chips ever? why is the pin count of the package part of the feature choice? etc.)
• What the generated API would look like (hard to infer from the YAML)
• Why I would port an svd2rust-based existing application (and I am no fan of svd2rust, to be clear, so I'm very much your target audience, I think)

I think this could be improved by

1. Including some top-level docs in the crate summarizing what it is, why it looks very generic on docs.rs, and how to get to model-specific docs if they can't be easily viewed through docs.rs.
2. Including at least one brief code example showing off some pleasant APIs, even if it's specific to a single model of chip (to give a visitor a sense of what your code generator is doing).
3. Updating the README here with, ideally, a link to the docs for every model (or a link to a generated file with that list). (Saw the spreadsheet; it's not really what I'm after)

Finally, when I saw "Register blocks for all peripherals" marked as "work in progress" I would normally have turned around and walked away -- the register blocks for peripherals are basically the whole reason I use a PAC in the first place. But I see this is being used by some projects, so, it might be worth providing something more specific than "work in progress." For instance: are there devices/subfamilies where you're pretty sure the registers are correct and/or complete? Currently I'm going to need to go through and audit all the decisions related to peripheral mapping to my target micros, as I've previously done for the SVDs and giant stack of YAML patches in the other crate I've used, and having a sense of whether the file I'm reading is expected to be correct or a "work in progress" would be very helpful.

Thanks again for putting this together, and I hope this was helpful instead of sounding like a bunch of complaints. I would like something like this approach to succeed!