Doc improvements

[TheZoq2]

There is always room for better documentation. This issue is a list of areas where the docs could use improvements. If you come across issues, please add them as a comment :)

Module level

• [ ] Finding which bus to pass to functions taking <$device as RccBus>::Bus could be made easier
• [ ] rtc references examples without linking to them
• [ ] adc is missing top level documentation
• [ ] i2c is missing docs in general
• [x] spi is missing top level docs
• [ ] timer is missing top level docs

Examples

• [ ] DMA example does not make it clear how to handle ownership over DMA in loops

Readme and getting started

• [ ] Examples require adding extra dependencies if used in standalone crate (at least panic-halt, and nb for blinky)
• [ ] Blinky example in Readme takes clock by value rather than reference
• General troubleshooting and common errors
  • [ ] eh_personality. Need to set target when compiling

[jamwaffles]

Some other points I've found whilst browsing through the docs:

• [ ] Peripherals need some basic usage examples. Not entire programs, but something that can be copypastad into an example. Off the top of my head:

  • [ ] QEI (#189)
  • [ ] I2C (#24)
  • [x] SPI
  • [ ] UART
  • [ ] PWM

  I think these probably overlap with the "general docs" points raised above but I think it's important to add examples with any new docs.

• [ ] REMAPped pins could use some examples. I can't remember what I hit last time, but IIRC I had problems getting the remapping to work.

[therealprof]

@jamwaffles We do have examples in the repository. It would be nice if we could find a way to just point to them or somehow include them in the documentation instead of having to manually maintain a commentified copy which are often (unnoticeable) buggy or go stale.

[jamwaffles]

Yeah it's a tradeoff really. As a middlingly-experience user of this crate, having short code examples to copy and paste would be useful, even if they are stale. It would be perfect if there was a way to include_str!() in doc comments. That said, we don't even test them in CI/at all at the moment so maybe that needs fixing first :(

[TheZoq2]

• [ ] Some issuse related to the NVIC were pointed out in #198