stm32f1xx-hal
stm32f1xx-hal copied to clipboard
Doc improvements
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
, andnb
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
- [ ]
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.
@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.
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 :(
- [ ] Some issuse related to the NVIC were pointed out in #198