Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WIP: Tidy #827

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

WIP: Tidy #827

wants to merge 2 commits into from

Conversation

ianrrees
Copy link
Contributor

Summary

Mostly warning cleanup, a few typos etc.

I'm finding the documentation of feature-gated APIs to be quite awkward... Wondering if it might be easier to add dummy methods/types that are conditional on documentation builds with the feature not enabled, so that rustdoc has something to link to. Eg

#[cfg(all(doc, not(feature = "dma")))]
/// Documentation was built without `dma` feature enabled
pub mod dmac {}

@ianrrees
Provide defmt feature in BSPs
5c72905 
Firmware that implements `defmt::Format` on types from the HAL requires
the HAL to be built with the defmt feature enabled.  This change adds a
`defmt` feature to each BSP so that users of the BSP can access the
HAL's `defmt` feature.

  #[derive(defmt::Format, Debug)]
  enum Error {
      UartError(hal::sercom::uart::Error),
     // ...more variants...
  }
@ianrrees ianrrees added the RFC Request for comments label Mar 12, 2025
@ianrrees
Copy link
Contributor Author

For this push, I've abandoned the idea of cleaning up all the cargo doc warnings without the dma and async features enabled. There are quite a lot of warnings aside from the docs for those features, and it's not clear to me what the best approach is for the feature-related docs.

I'm tempted to suggest that we put a CI check in place to flag documentation warnings, though I suppose that would add a little bit of friction to documenting which isn't great...

@jbeaurivage
Copy link
Contributor

No worries. I thought about it a bit, and I feel like it would be beneficial to have all docs enabled all the time, even if a specific feature is disabled. Ie, if the async feature is disabled, it would be nice if the docs would still get built. Maybe in an otherwise empty module, and a message prompting to enable the feature?

I'm not too sure what would be the best approach to achieve this. Thoughts?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
RFC Request for comments
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@ianrrees @jbeaurivage