Skip to content

Commit

Permalink
move BitfieldSpecifier docs to impl
Browse files Browse the repository at this point in the history
  • Loading branch information
@Robbepop
Robbepop committed Oct 29, 2020
1 parent 8f0c57b commit c91cb8b
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 153 deletions.
142 changes: 119 additions & 23 deletions impl/src/lib.rs
View file
Expand Up @@ -77,39 +77,135 @@ pub fn bitfield(args: TokenStream, input: TokenStream) -> TokenStream {
bitfield::analyse_and_expand(args.into(), input.into()).into()
}

/// Derive macro for enums.
/// Derive macro for Rust `enums` to implement `Specifier` trait.
///
/// Generates code for enums to make them usable within `#[bitfield]` structs.
/// Performs compile-time checks to validate that the enum is usable as bitfield specifier.
/// This allows such an enum to be used as a field of a `#[bitfield]` struct.
/// The annotated enum must not have any variants with associated data and
/// by default must have a number of variants that is equal to the power of 2.
///
/// ## Example
/// If a user wants to circumvent the latter restriction they can add
/// `#[bits = N]` below the `#[derive(BitfieldSpecifier)]` line in order to
/// signal to the code generation that the enum may have a relaxed number
/// of variants.
///
/// # Example
///
/// ## Example: Basic Usage
///
/// In the following we define a `MaybeWeekday` enum that lists all weekdays
/// as well as an invalid day so that we have a power-of-two number of variants.
///
/// ```
/// use modular_bitfield::prelude::*;
///
/// #[bitfield]
/// struct Example {
/// a: bool, // Uses 1 bit
/// b: Mode, // Has 4 variants => uses 2 bits
/// c: B5, // Uses 5 bits
/// d: B24, // Uses 24 bits
/// #[derive(BitfieldSpecifier)]
/// pub enum Weekday {
/// Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, None
/// }
/// ```
///
/// ## Example: `#[bits = N]`
///
/// #[derive(BitfieldSpecifier, Debug, PartialEq, Eq)]
/// pub enum Mode {
/// Sleep,
/// Awake,
/// Working,
/// Lazy,
/// If we want to get rid of the `None` variant we need to add `#[bits = 3]`:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// #[derive(BitfieldSpecifier)]
/// #[bits = 3]
/// pub enum Weekday {
/// Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
/// }
/// ```
///
/// let mut example = Example::new();
/// assert_eq!(example.a(), false); // `false as u8` is 0
/// assert_eq!(example.b(), Mode::Sleep);
/// example.set_a(true);
/// example.set_b(Mode::Awake);
/// assert_eq!(example.a(), true); // `true as u8` is 1
/// assert_eq!(example.b(), Mode::Awake);
/// ## Example: Discriminants
///
/// It is possible to explicitly assign discriminants to some of the days.
/// In our case this is useful since our week starts at sunday:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// #[derive(BitfieldSpecifier)]
/// #[bits = 3]
/// pub enum Weekday {
/// Monday = 1,
/// Tuesday = 2,
/// Wednesday = 3,
/// Thursday = 4,
/// Friday = 5,
/// Saturday = 6,
/// Sunday = 0,
/// }
/// ```
///
/// ## Example: Use in `#[bitfield]`
///
/// Given the above `Weekday` enum that starts at `Sunday` and uses 3 bits in total
/// we can now use it in a `#[bitfield]` annotated struct as follows:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// # #[derive(BitfieldSpecifier)]
/// # #[bits = 3]
/// # pub enum Weekday {
/// # Monday = 1,
/// # Tuesday = 2,
/// # Wednesday = 3,
/// # Thursday = 4,
/// # Friday = 5,
/// # Saturday = 6,
/// # Sunday = 0,
/// # }
/// #[bitfield]
/// pub struct MeetingTimeSlot {
/// day: Weekday,
/// from: B6,
/// to: B6,
/// expired: bool,
/// }
/// ```
///
/// The above `MeetingTimeSlot` uses exactly 16 bits and defines our `Weekday` enum as
/// compact `day` bitfield. The `from` and `to` require 6 bits each and finally the
/// `expired` flag requires a single bit.
///
/// ## Example: Interacting
///
/// A user can interact with the above `MeetingTimeSlot` and `Weekday` definitions in
/// the following ways:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// # #[derive(BitfieldSpecifier, Debug, PartialEq)]
/// # #[bits = 3]
/// # pub enum Weekday {
/// # Monday = 1,
/// # Tuesday = 2,
/// # Wednesday = 3,
/// # Thursday = 4,
/// # Friday = 5,
/// # Saturday = 6,
/// # Sunday = 0,
/// # }
/// # #[bitfield]
/// # pub struct MeetingTimeSlot {
/// # day: Weekday,
/// # from: B6,
/// # to: B6,
/// # expired: bool,
/// # }
/// #
/// let mut slot = MeetingTimeSlot::new()
/// .with_day(Weekday::Friday)
/// .with_from(14) // 14:00 CEST
/// .with_to(15); // 15:00 CEST
/// assert_eq!(slot.day(), Weekday::Friday);
/// assert_eq!(slot.from(), 14);
/// assert_eq!(slot.to(), 15);
/// assert!(!slot.expired());
/// ```
#[proc_macro_derive(BitfieldSpecifier, attributes(bits))]
pub fn bitfield_specifier(input: TokenStream) -> TokenStream {
Expand Down
130 changes: 0 additions & 130 deletions src/lib.rs
View file
Expand Up @@ -345,136 +345,6 @@

pub use modular_bitfield_impl::bitfield;

/// Derive macro for Rust `enums` to implement [`Specifier`] trait.
///
/// This allows such an enum to be used as a field of a `#[bitfield]` struct.
/// The annotated enum must not have any variants with associated data and
/// by default must have a number of variants that is equal to the power of 2.
///
/// If a user wants to circumvent the latter restriction they can add
/// `#[bits = N]` below the `#[derive(BitfieldSpecifier)]` line in order to
/// signal to the code generation that the enum may have a relaxed number
/// of variants.
///
/// # Example
///
/// ## Example: Basic Usage
///
/// In the following we define a `MaybeWeekday` enum that lists all weekdays
/// as well as an invalid day so that we have a power-of-two number of variants.
///
/// ```
/// use modular_bitfield::prelude::*;
///
/// #[derive(BitfieldSpecifier)]
/// pub enum Weekday {
/// Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, None
/// }
/// ```
///
/// ## Example: #[bits = N]
///
/// If we want to get rid of the `None` variant we need to add `#[bits = 3]`:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// #[derive(BitfieldSpecifier)]
/// #[bits = 3]
/// pub enum Weekday {
/// Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
/// }
/// ```
///
/// ## Example: Discriminants
///
/// It is possible to explicitly assign discriminants to some of the days.
/// In our case this is useful since our week starts at sunday:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// #[derive(BitfieldSpecifier)]
/// #[bits = 3]
/// pub enum Weekday {
/// Monday = 1,
/// Tuesday = 2,
/// Wednesday = 3,
/// Thursday = 4,
/// Friday = 5,
/// Saturday = 6,
/// Sunday = 0,
/// }
/// ```
///
/// ## Example: Use in #[bitfield]
///
/// Given the above `Weekday` enum that starts at `Sunday` and uses 3 bits in total
/// we can now use it in a `#[bitfield]` annotated struct as follows:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// # #[derive(BitfieldSpecifier)]
/// # #[bits = 3]
/// # pub enum Weekday {
/// # Monday = 1,
/// # Tuesday = 2,
/// # Wednesday = 3,
/// # Thursday = 4,
/// # Friday = 5,
/// # Saturday = 6,
/// # Sunday = 0,
/// # }
/// #[bitfield]
/// pub struct MeetingTimeSlot {
/// day: Weekday,
/// from: B6,
/// to: B6,
/// expired: bool,
/// }
/// ```
///
/// The above `MeetingTimeSlot` uses exactly 16 bits and defines our `Weekday` enum as
/// compact `day` bitfield. The `from` and `to` require 6 bits each and finally the
/// `expired` flag requires a single bit.
///
/// ## Example: Interacting
///
/// A user can interact with the above `MeetingTimeSlot` and `Weekday` definitions in
/// the following ways:
///
/// ```
/// # use modular_bitfield::prelude::*;
/// #
/// # #[derive(BitfieldSpecifier, Debug, PartialEq)]
/// # #[bits = 3]
/// # pub enum Weekday {
/// # Monday = 1,
/// # Tuesday = 2,
/// # Wednesday = 3,
/// # Thursday = 4,
/// # Friday = 5,
/// # Saturday = 6,
/// # Sunday = 0,
/// # }
/// # #[bitfield]
/// # pub struct MeetingTimeSlot {
/// # day: Weekday,
/// # from: B6,
/// # to: B6,
/// # expired: bool,
/// # }
/// #
/// let mut slot = MeetingTimeSlot::new()
/// .with_day(Weekday::Friday)
/// .with_from(14) // 14:00 CEST
/// .with_to(15); // 15:00 CEST
/// assert_eq!(slot.day(), Weekday::Friday);
/// assert_eq!(slot.from(), 14);
/// assert_eq!(slot.to(), 15);
/// assert!(!slot.expired());
/// ```
pub use modular_bitfield_impl::BitfieldSpecifier;

#[doc(hidden)]
Expand Down

0 comments on commit c91cb8b

Please sign in to comment.