search

dzamlo / rust-bitfield

This crate provides macros to generate bitfield-like struct.
Apache License 2.0
157 stars 19 forks source link

Document attributes #17

Open asomers opened 6 years ago

asomers commented 6 years ago

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.

asomers commented 6 years ago

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.

dzamlo commented 6 years ago

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)

asomers commented 6 years ago

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.

JayKickliter commented 6 years ago

I've been using this crate for about a year now, and also only just realized I could add attributes.