Rustdoc output would benefit from some top-level docs / some readme suggestions

[cbiffle]

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!

[Dirbaio]

Yeah, 100% agree there's lots of room for improvement on docs.

You can see docs for a particular chip at https://docs.embassy.dev/stm32-metapac, just pick the chip from the top menu. Sadly docs.rs doesn't support building docs multiple times for different features.

[cbiffle]

Oh, that link is fantastic. Can I send a PR adding it near the top of the README to ensure that new visitors find it?

Sadly docs.rs doesn't support building docs multiple times for different features.

Or targets, for that matter! It's a great service but very limited.

I'm quite happy to help with the docs, fwiw. I'm rather familiar with the STM32 family and have been looking for an alternate PAC. I would need a couple of pointers for getting started -- in particular, any worked example that shows how you're expecting your APIs to be used would be very helpful, as inferring that from generated code can be difficult. But since I'm bringing up an stm32c011 board and your support seems like the most mature, I'm quite motivated to help.

[cbiffle]

Couldn't find an example using a recent version of the crate, so, wrote one by reverse engineering the generated code. Maybe this will help someone else!

https://github.com/cbiffle/stm32c0-metapac-example

It works (though note that you need a post-0.12 git build of openocd to actually program the part). So far I like your generated APIs quite a bit. The quality of the generated code is similar to, but possibly slightly less compact than, svd2rust-generated equivalents. I'll investigate that further as I port a real application over.

Is there an area where you'd be most excited about rustdoc help?