doc: Add example expansion for register_bitfields! macro #4230
Conversation
|
Fixes #4222. |
There was a problem hiding this comment.
Thanks for this contribution, this is great!
I'm slightly worried this might be too detailed for the purposes of a README. On the one hand, we wouldn't want to elide too many details or oversimplify, as it's important for developers to understand exactly what these macros document. However, if we give too many details, then we lose out on the utility of this documentation.
I think this is close. Next to the suggestions in the code, I would maybe remove the expanded Status and InterruptFlags expansions. They don't add too much, Control seems to encompass all the types & values we're generating.
While InterruptFlags could maybe be interesting, it's also just a (seldomly used) simplification of the full syntax. In fact, it might be best to instead expand the InterruptFlags example itself (on lines 181 to 189) to also include an example (in a comment) on how this maps to the full syntax as used by Control and Status.
b0d60a3 to
5575d71
Compare
5575d71 to
f1e6381
Compare
Signed-off-by: Dragos Coscodan <[email protected]>
f1e6381 to
c5fa7af
Compare
Co-authored-by: Leon Schuermann <[email protected]>
Pull Request Overview
This pull request adds an example of the expanded output from the register_bitfields! macro. The example focuses on the central part of the generated code, providing clarity on how the bitfield structure, including field types and operator overloads, is created.
Testing Strategy
I ran the code using the register_bitfields! macro and employed cargo expand to inspect the generated output. After analyzing the code, I incorporated the concise version into the documentation to provide an example of the macro’s behavior.
TODO or Help Wanted
N/A
Documentation Updated
/docs, or no updates are required.Formatting
make prepush.