rust-bitfield
rust-bitfield copied to clipboard
dzamlo
Document attributes
It looks like the bitfield macro supports placing pretty much any compiler attribute on the struct or on any field. This is very useful, especially for doing things like #[derive(Clone)]. But it's not documented anywhere. Ideally it should be documented in the API docs and in the examples.
Also, it would be good to show an example of documenting the generated struct. Placing doc comments above the pub struct line seems to work.
This is documented with the phrase "The syntax of this macro is the syntax of a tuple struct, including attributes and documentation comments, " on https://docs.rs/bitfield/0.13.0/bitfield/macro.bitfield.html for the struct and as the first element of list following "A field declaration is composed of the following:" on https://docs.rs/bitfield/0.13.0/bitfield/macro.bitfield_fields.html for the fields.
Do you think that adding that using that in the example would be enough to make it clear and discoverable ?
(as a side note, documentation comments are transformed into an attribute by the rust compiler before they reach the macro. This means that if you have a macro that support arbitrary attributes, it also support documentation comments)
The current documentation isn't very clear. I didn't realize that I could attach attributes until I had read the source. Examples would be very helpful.
I've been using this crate for about a year now, and also only just realized I could add attributes.
