Skip to content

Commit

Permalink
docs(bitfield): replace tables with bulleted lists (#451)
Browse files Browse the repository at this point in the history
  • Loading branch information
hawkw authored Jul 22, 2023
1 parent c8d6e0c commit 10cd876
Showing 1 changed file with 55 additions and 22 deletions.
77 changes: 55 additions & 22 deletions bitfield/src/bitfield.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,40 @@
/// `{int}` is the integer type that represents the bitfield (one of `u8`,
/// `u16`,`u32`, `u64`, or `usize`):
///
/// | Function | Description |
/// |:--|:--|
/// | `const fn new() -> Self` | Returns a new instance of the bitfield type with all bits zeroed. |
/// | `const fn from_bits(bits: {int}) -> Self` | Converts an `{int}` into an instance of the bitfield type. |
/// | `const fn bits(self) -> {int}` | Returns this bitfield's bits as a raw integer value. |
/// | `fn with<U>(self, packer: Self::Packer<U>, value: U) -> Self` | Given one of this type's generated packing specs for a `U`-typed value, and a `U`-typed value, returns a new instance of `Self` with the bit representation of `value` packed into the range represented by `packer`. |
/// | `fn set<U>(&mut self, packer: Self::Packer<U>, value: U) -> &mut Self` | Similar to `with`, except `self` is mutated in place, rather than returning a new instance of `Self`. |
/// | `fn get<U>(&self, packer: Self::Packer<U>) -> U` | Given one of this type's generated packing specs for a `U`-typed value, unpacks the bit range represented by that value as a `U` and returns it. This method panics if the requested bit range does not contain a valid bit pattern for a `U`-typed value, as determined by `U`'s implementation of the [`FromBits`] trait. |
/// | `fn try_get<U>(&self, packer: Self::Packer<U>) -> Result<U, <U as FromBits>::Error>` | Like `get`, but returns a `Result` instead of panicking. |
/// | `fn assert_valid()` | Asserts that the generated bitfield type is valid. This is primarily intended to be used in tests; the macro cannot generate tests for a bitfield type on its own, so a test that simply calls `assert_valid` can be added to check the bitfield type's validity. |
/// | `fn display_ascii(&self) -> impl core::fmt::Display` | Returns a `Display` implementation that formats the bitfield in a multi-line format, using only ASCII characters. See [here](#example-display-output) for examples of this format. |
/// | `fn display_unicode(&self) -> impl core::fmt::Display` | Returns a `Display` implementation that formats the bitfield in a multi-line format, always using Unicode box-drawing characters. See [here](#example-display-output) for examples of this format. |
/// - `const fn new() -> Self`: Returns a new instance of the bitfield type with
/// all bits zeroed.
/// - `const fn from_bits(bits: {int}) -> Self`: Converts an `{int}` into an
/// instance of the bitfield type.
/// - `const fn bits(self) -> {int}`: Returns this bitfield's bits as a raw
/// integer value.
/// - `fn with<U>(self, packer: Self::Packer<U>, value: U) -> Self`: Given one
/// of this type's generated packing specs for a `U`-typed value, and a
/// `U`-typed value, returns a new instance of `Self` with the bit
/// representation of `value` packed into the range represented by `packer`.
/// - `fn set<U>(&mut self, packer: Self::Packer<U>, value: U) -> &mut Self`:
/// Similar to `with`, except `self` is mutated in place, rather than
/// returning a new nstance of `Self`
/// - `fn get<U>(&self, packer: Self::Packer<U>) -> U`: Given one of this type's
/// generated packing specs for a `U`-typed value, unpacks the bit range
/// represented by that value as a `U` and returns it. This method panics if
/// the requested bit range does not contain a valid bit pattern for a
/// `U`-typed value, as determined by `U`'s implementation of the [`FromBits`]
/// trait.
/// - `fn try_get<U>(&self, packer: Self::Packer<U>) -> Result<U, <U as
/// FromBits>::Error>`: Like `get`, but returns a `Result` instead of
/// panicking.
/// - `fn assert_valid()`: Asserts that the generated bitfield type is valid.
/// This is primarily intended to be used in tests; the macro cannot generate
/// tests for a bitfield type on its own, so a test that simply calls
/// `assert_valid` can be added to check the bitfield type's validity.
/// - `fn display_ascii(&self) -> impl core::fmt::Display`: Returns a
/// [`fmt::Display`] implementation that formats the bitfield in a multi-line
/// format, using only ASCII characters. See [here](#example-display-output)
/// for examples of this format.
/// - `fn display_unicode(&self) -> impl core::fmt::Display`: Returns a
/// [`fmt::Display`] implementation that formats the bitfield in a multi-line
/// format, always using Unicode box-drawing characters. See
/// [here](#example-display-output) for examples of this format.
///
/// The visibility of these methods depends on the visibility of the bitfield
/// struct --- if the struct is defined as `pub(crate) struct MyBitfield<u16> {
Expand All @@ -42,16 +64,27 @@
/// In addition to the inherent methods discussed above, the following trait
/// implementations are always generated:
///
/// | Trait | Description |
/// |:--|:--|
/// | [`fmt::Debug`] | The `Debug` implementation prints the bitfield as a "struct", with a "field" for each packing spec in the bitfield. If any of the bitfield's packing specs pack typed values, that type's [`fmt::Debug`] implementation is used rather than printing the value as an integer. |
/// | [`fmt::Binary`] | Prints the raw bits of this bitfield as a binary number. |
/// | [`fmt::UpperHex`] and [`fmt::LowerHex`] | Prints the raw bits of this bitfield in hexadecimal. |
/// | [`fmt::Display`] | Pretty-prints the bitfield in a very nice-looking multi-line format which I'm rather proud of. See [here](#example-display-output) for examples of this format. |
/// | [`Copy`] | Behaves identically as the [`Copy`] implementation for the underlying integer type. |
/// | [`Clone`] | Behaves identically as the [`Clone`] implementation for the underlying integer type. |
/// | [`From`]`<{int}> for Self` | Converts a raw integer value into an instance of the bitfield type. This is equivalent to calling the bitfield type's `from_bits` function. |
/// | [`From`]`<Self> for {int}` | Converts an instance of the bitfield type into a raw integer value. This is equivalent to calling the bitfield type's `bits` method. |
/// - [`fmt::Debug`]: The `Debug` implementation prints the bitfield as a
/// "struct", with a "field" for each packing spec in the bitfield. If any
/// of the bitfield's packing specs pack typed values, that type's
/// [`fmt::Debug`] implementation is used rather than printing the value
/// as an integer.
/// - [`fmt::Binary`]: Prints the raw bits of this bitfield as a binary number.
/// - [`fmt::UpperHex`] and [`fmt::LowerHex`]: Prints the raw bits of this
/// bitfield in hexadecimal.
/// - [`fmt::Display`]: Pretty-prints the bitfield in a very nice-looking
/// multi-line format which I'm rather proud of. See
/// [here](#example-display-output) for examples of this format.
/// - [`Copy`]: Behaves identically as the [`Copy`] implementation for the
/// underlying integer type.
/// - [`Clone`]: Behaves identically as the [`Clone`] implementation for the
/// underlying integer type.
/// - [`From`]`<{int}> for Self`: Converts a raw integer value into an instance
/// of the bitfield type. This is equivalent to calling the bitfield type's
/// `from_bits` function.
/// - [`From`]`<Self> for {int}`: Converts an instance of the bitfield type into
/// a raw integer value. This is equivalent to calling the bitfield type's
/// `bits` method.
///
/// Additional traits may be derived for the bitfield type, such as
/// [`PartialEq`], [`Eq`], and [`Default`]. These traits are not automatically
Expand Down

0 comments on commit 10cd876

Please sign in to comment.