Documentation improvements

[jessebraham]

There are a number of changes we would like to make to our documentation, so this will serve as a tracking issue (or an "epic", if you will) for each individual task.

If you would like to complete one of these tasks, please assign yourself to the issue if one already exists, or create a new issue and assign yourself to it.

• [ ] https://github.com/esp-rs/esp-hal/issues/992
  • Some discussion will need to be had which features (all?) should be enabled when building documentation.
• [x] https://github.com/esp-rs/esp-hal/issues/1095
• [ ] Use the unstable doc_cfg feature to document which cargo features are required for modules/types/etc.
  • See espflash docs for example of this: https://docs.rs/espflash/latest/espflash/
  • Requires:
    • ~~Package metadata: https://github.com/esp-rs/espflash/blob/main/espflash/Cargo.toml#L17-L18~~
    • Global attr: https://github.com/esp-rs/espflash/blob/main/espflash/src/lib.rs#L28
    • Per-module/-type attrs: https://github.com/esp-rs/espflash/blob/main/espflash/src/lib.rs#L30-L32
• [x] https://github.com/esp-rs/esp-hal/issues/1204
• [x] Remove references to chip-specific HAL packages (if any remain)
• [ ] Avoid documenting features that don't apply to the current chip/cfg away (or add) chip specific documentation for drivers
• [ ] https://github.com/esp-rs/esp-hal/issues/1225
• [x] https://github.com/esp-rs/esp-hal/issues/1233
• [x] #1276
• [ ] It would be nice to list which peripherals are and aren't supported for each device
  • JB: This can probably be automated, will look into it
• [ ] We should be explicit about which drivers provide blocking and/or async APIs
  • JB: This can probably be automated, will look into it
• [x] https://github.com/esp-rs/esp-hal/issues/1261
• [ ] Some module level docs need a complete overhaul
  • [ ] interrupt module is too generic, and the example isn't correct. Improved via https://github.com/esp-rs/esp-hal/pull/1310

[AnthonyGrondin]

Not sure where to drop this, but if we want to test for documentation coverage of the public APIs in CI, we could do something like:

cargo rustdoc -q -- -Z unstable-options --show-coverage | grep -i total | grep -oE '[0-9]*\.[0-9]*%' | head -n1 | grep -q 100.0%

1. Get lists of documentation coverage
2. Get the last line, "total"
3. Extract both percentage (doc, examples) from the line.
4. Get first one (doc)
5. Check if == 100%.

[bjoernQ]

We probably also want to double check what we want to hide from the docs

e.g. here: https://docs.rs/esp32s3-hal/0.15.0/esp32s3_hal/gpio/index.html - GpioXSignals is pretty much useless for users of the HAL

https://docs.rs/esp32s3-hal/0.15.0/esp32s3_hal/gpio/trait.GpioProperties.html - the whole trait is probably cryptic and useless for most users

Not a priority but always I look into the docs I think about this and quickly forget about then

[playfulFence]

Working on #1276

[jessebraham]

@MabezDev maybe we can split out any remaining tasks which we still intend to tackle and close this? I think it will be an eternal issue otherwise.

[MabezDev]

@jessebraham I agree, I skimmed the list of unticked boxes and nothing really jumped out at me - feel free to convert any if you feel differently but I'll close this now.