From ea40e7fff0d0e1ef3ac121cd734c5b2e058b9a04 Mon Sep 17 00:00:00 2001 From: KodrAus Date: Fri, 14 Jul 2023 16:20:18 +1000 Subject: [PATCH] align docs to spec terminology --- src/lib.rs | 79 ++++++++++++++++----------------------------- src/public.rs | 36 ++++++++++++++------- src/traits.rs | 88 ++++++++++++++++++++++++++++----------------------- 3 files changed, 101 insertions(+), 102 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index ffeef79b..5ff36a66 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -723,74 +723,73 @@ macro_rules! __impl_bitflags { ) => { #[allow(dead_code, deprecated, unused_attributes)] impl $PublicBitFlags { - /// Returns an empty set of flags. + /// Get a flags value with all bits unset. #[inline] pub const fn empty() -> Self { $empty } - /// Returns the set containing all flags. + /// Get a flags value with all known bits set. #[inline] pub const fn all() -> Self { $all } - /// Returns the raw value of the flags currently stored. + /// Get the underlying bits value. + /// + /// The returned value is exactly the bits set in this flags value. #[inline] pub const fn bits(&self) -> $T { let $bits0 = self; $bits } - /// Convert from underlying bit representation, unless that - /// representation contains bits that do not correspond to a flag. + /// Convert from a bits value, unless any unset bits are set. #[inline] pub const fn from_bits(bits: $T) -> $crate::__private::core::option::Option { let $from_bits0 = bits; $from_bits } - /// Convert from underlying bit representation, dropping any bits - /// that do not correspond to flags. + /// Convert from a bits value, unsetting any unknown bits. #[inline] pub const fn from_bits_truncate(bits: $T) -> Self { let $from_bits_truncate0 = bits; $from_bits_truncate } - /// Convert from underlying bit representation, preserving all - /// bits (even those not corresponding to a defined flag). + /// Convert from a bits value, without altering them in any way. #[inline] pub const fn from_bits_retain(bits: $T) -> Self { let $from_bits_retain0 = bits; $from_bits_retain } - /// Get the value for a flag from its stringified name. + /// Get a flags value with the bits of a flag with the given name set. /// - /// Names are _case-sensitive_, so must correspond exactly to - /// the identifier given to the flag. + /// This method will return `None` if `name` is empty or doesn't + /// correspond to any named flag. #[inline] pub fn from_name(name: &str) -> $crate::__private::core::option::Option { let $from_name0 = name; $from_name } - /// Returns `true` if no flags are currently stored. + /// Whether all bits in this flags value are unset. #[inline] pub const fn is_empty(&self) -> bool { let $is_empty0 = self; $is_empty } - /// Returns `true` if all flags are currently set. + /// Whether all defined flags are contained in this flags value. #[inline] pub const fn is_all(&self) -> bool { let $is_all0 = self; $is_all } - /// Returns `true` if there are flags common to both `self` and `other`. + /// Whether any set bits in a source flags value are also set in a target flags value. #[inline] pub const fn intersects(&self, other: Self) -> bool { let $intersects0 = self; @@ -798,7 +797,7 @@ macro_rules! __impl_bitflags { $intersects } - /// Returns `true` if all of the flags in `other` are contained within `self`. + /// Whether all set bits in a source flags value are also set in a target flags value. #[inline] pub const fn contains(&self, other: Self) -> bool { let $contains0 = self; @@ -806,9 +805,7 @@ macro_rules! __impl_bitflags { $contains } - /// Inserts the specified flags in-place. - /// - /// This method is equivalent to `union`. + /// The bitwise or (`|`) of the bits in two flags values. #[inline] pub fn insert(&mut self, other: Self) { let $insert0 = self; @@ -816,9 +813,10 @@ macro_rules! __impl_bitflags { $insert } - /// Removes the specified flags in-place. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). /// - /// This method is equivalent to `difference`. + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `remove` won't truncate `other`, but the `!` operator will. #[inline] pub fn remove(&mut self, other: Self) { let $remove0 = self; @@ -826,9 +824,7 @@ macro_rules! __impl_bitflags { $remove } - /// Toggles the specified flags in-place. - /// - /// This method is equivalent to `symmetric_difference`. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. #[inline] pub fn toggle(&mut self, other: Self) { let $toggle0 = self; @@ -836,7 +832,7 @@ macro_rules! __impl_bitflags { $toggle } - /// Inserts or removes the specified flags depending on the passed value. + /// Call `insert` when `value` is `true` or `remove` when `value` is `false`. #[inline] pub fn set(&mut self, other: Self, value: bool) { let $set0 = self; @@ -845,11 +841,7 @@ macro_rules! __impl_bitflags { $set } - /// Returns the intersection between the flags in `self` and - /// `other`. - /// - /// Calculating `self` bitwise and (`&`) other, including - /// any bits that don't correspond to a defined flag. + /// The bitwise and (`&`) of the bits in two flags values. #[inline] #[must_use] pub const fn intersection(self, other: Self) -> Self { @@ -858,10 +850,7 @@ macro_rules! __impl_bitflags { $intersection } - /// Returns the union of between the flags in `self` and `other`. - /// - /// Calculates `self` bitwise or (`|`) `other`, including - /// any bits that don't correspond to a defined flag. + /// The bitwise or (`|`) of the bits in two flags values. #[inline] #[must_use] pub const fn union(self, other: Self) -> Self { @@ -870,15 +859,10 @@ macro_rules! __impl_bitflags { $union } - /// Returns the difference between the flags in `self` and `other`. - /// - /// Calculates `self` bitwise and (`&!`) the bitwise negation of `other`, - /// including any bits that don't correspond to a defined flag. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). /// - /// This method is _not_ equivalent to `a & !b` when there are bits set that - /// don't correspond to a defined flag. The `!` operator will unset any - /// bits that don't correspond to a flag, so they'll always be unset by `a &! b`, - /// but respected by `a.difference(b)`. + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `difference` won't truncate `other`, but the `!` operator will. #[inline] #[must_use] pub const fn difference(self, other: Self) -> Self { @@ -887,11 +871,7 @@ macro_rules! __impl_bitflags { $difference } - /// Returns the symmetric difference between the flags - /// in `self` and `other`. - /// - /// Calculates `self` bitwise exclusive or (`^`) `other`, - /// including any bits that don't correspond to a defined flag. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. #[inline] #[must_use] pub const fn symmetric_difference(self, other: Self) -> Self { @@ -900,10 +880,7 @@ macro_rules! __impl_bitflags { $symmetric_difference } - /// Returns the complement of this set of flags. - /// - /// Calculates the bitwise negation (`!`) of `self`, - /// **unsetting** any bits that don't correspond to a defined flag. + /// The bitwise negation (`!`) of the bits in a flags value, truncating the result. #[inline] #[must_use] pub const fn complement(self) -> Self { diff --git a/src/public.rs b/src/public.rs index 1952dced..d0537cc7 100644 --- a/src/public.rs +++ b/src/public.rs @@ -273,7 +273,10 @@ macro_rules! __impl_public_bitflags { macro_rules! __impl_public_bitflags_iter { ($BitFlags:ident: $T:ty, $PublicBitFlags:ident) => { impl $BitFlags { - /// Iterate over enabled flag values. + /// Yield a set of contained flags values. + /// + /// Each yielded flags value will correspond to a defined named flag. Any unknown bits + /// will be yielded together as a final flags value. #[inline] pub const fn iter(&self) -> $crate::iter::Iter<$PublicBitFlags> { $crate::iter::Iter::__private_const_new( @@ -283,7 +286,10 @@ macro_rules! __impl_public_bitflags_iter { ) } - /// Iterate over enabled flag values with their stringified names. + /// Yield a set of contained named flags values. + /// + /// This method is like [`iter`], except only yields bits in contained named flags. + /// Any unknown bits, or bits not corresponding to a contained flag will not be yielded. #[inline] pub const fn iter_names(&self) -> $crate::iter::IterNames<$PublicBitFlags> { $crate::iter::IterNames::__private_const_new( @@ -349,7 +355,7 @@ macro_rules! __impl_public_bitflags_ops { impl $crate::__private::core::ops::BitOr for $PublicBitFlags { type Output = Self; - /// Returns the union of the two sets of flags. + /// The bitwise or (`|`) of the bits in two flags values. #[inline] fn bitor(self, other: $PublicBitFlags) -> Self { self.union(other) @@ -357,7 +363,7 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::ops::BitOrAssign for $PublicBitFlags { - /// Adds the set of flags. + /// The bitwise or (`|`) of the bits in two flags values. #[inline] fn bitor_assign(&mut self, other: Self) { self.insert(other); @@ -367,7 +373,7 @@ macro_rules! __impl_public_bitflags_ops { impl $crate::__private::core::ops::BitXor for $PublicBitFlags { type Output = Self; - /// Returns the left flags, but with all the right flags toggled. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. #[inline] fn bitxor(self, other: Self) -> Self { self.symmetric_difference(other) @@ -375,7 +381,7 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::ops::BitXorAssign for $PublicBitFlags { - /// Toggles the set of flags. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. #[inline] fn bitxor_assign(&mut self, other: Self) { self.toggle(other); @@ -385,7 +391,7 @@ macro_rules! __impl_public_bitflags_ops { impl $crate::__private::core::ops::BitAnd for $PublicBitFlags { type Output = Self; - /// Returns the intersection between the two sets of flags. + /// The bitwise and (`&`) of the bits in two flags values. #[inline] fn bitand(self, other: Self) -> Self { self.intersection(other) @@ -393,7 +399,7 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::ops::BitAndAssign for $PublicBitFlags { - /// Disables all flags disabled in the set. + /// The bitwise and (`&`) of the bits in two flags values. #[inline] fn bitand_assign(&mut self, other: Self) { *self = Self::from_bits_retain(self.bits()).intersection(other); @@ -403,7 +409,10 @@ macro_rules! __impl_public_bitflags_ops { impl $crate::__private::core::ops::Sub for $PublicBitFlags { type Output = Self; - /// Returns the set difference of the two sets of flags. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). + /// + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `difference` won't truncate `other`, but the `!` operator will. #[inline] fn sub(self, other: Self) -> Self { self.difference(other) @@ -411,7 +420,10 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::ops::SubAssign for $PublicBitFlags { - /// Disables all flags enabled in the set. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). + /// + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `difference` won't truncate `other`, but the `!` operator will. #[inline] fn sub_assign(&mut self, other: Self) { self.remove(other); @@ -421,7 +433,7 @@ macro_rules! __impl_public_bitflags_ops { impl $crate::__private::core::ops::Not for $PublicBitFlags { type Output = Self; - /// Returns the complement of this set of flags. + /// The bitwise negation (`!`) of the bits in a flags value, truncating the result. #[inline] fn not(self) -> Self { self.complement() @@ -429,6 +441,7 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::iter::Extend<$PublicBitFlags> for $PublicBitFlags { + /// The bitwise or (`|`) of the bits in each flags value. fn extend>( &mut self, iterator: T, @@ -440,6 +453,7 @@ macro_rules! __impl_public_bitflags_ops { } impl $crate::__private::core::iter::FromIterator<$PublicBitFlags> for $PublicBitFlags { + /// The bitwise or (`|`) of the bits in each flags value. fn from_iter>( iterator: T, ) -> Self { diff --git a/src/traits.rs b/src/traits.rs index e21a179f..4ca2465f 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -8,7 +8,7 @@ use crate::{ parser::{ParseError, ParseHex, WriteHex}, }; -/// Metadata for an individual flag. +/// A set of bits in a bits type that may have a unique name. pub struct Flag { name: &'static str, value: B, @@ -16,11 +16,15 @@ pub struct Flag { impl Flag { /// Create a new flag with the given name and value. + /// + /// If `name` is empty then the flag is unnamed. pub const fn new(name: &'static str, value: B) -> Self { Flag { name, value } } /// Get the name of this flag. + /// + /// If `name` is empty then the flag is unnamed. pub const fn name(&self) -> &'static str { self.name } @@ -31,23 +35,20 @@ impl Flag { } } -/// A set of flags. -/// -/// This trait is automatically implemented for flags types defined using the `bitflags!` macro. -/// It can also be implemented manually for custom flags types. +/// A set of defined flags over a specific bits type. pub trait Flags: Sized + 'static { - /// The set of available flags and their names. + /// The set of defined flags. const FLAGS: &'static [Flag]; - /// The underlying storage type. + /// The underlying bits type. type Bits: Bits; - /// Returns an empty set of flags. + /// Get a flags value with all bits unset. fn empty() -> Self { Self::from_bits_retain(Self::Bits::EMPTY) } - /// Returns the set containing all flags. + /// Get a flags value with all known bits set. fn all() -> Self { let mut truncated = Self::Bits::EMPTY; @@ -58,11 +59,12 @@ pub trait Flags: Sized + 'static { Self::from_bits_retain(truncated) } - /// Returns the raw value of the flags currently stored. + /// Get the underlying bits value. + /// + /// The returned value is exactly the bits set in this flags value. fn bits(&self) -> Self::Bits; - /// Convert from underlying bit representation, unless that - /// representation contains bits that do not correspond to a flag. + /// Convert from a bits value, unless any unset bits are set. fn from_bits(bits: Self::Bits) -> Option { let truncated = Self::from_bits_truncate(bits); @@ -73,17 +75,18 @@ pub trait Flags: Sized + 'static { } } - /// Convert from underlying bit representation, dropping any bits - /// that do not correspond to flags. + /// Convert from a bits value, unsetting any unknown bits. fn from_bits_truncate(bits: Self::Bits) -> Self { Self::from_bits_retain(bits & Self::all().bits()) } - /// Convert from underlying bit representation, preserving all - /// bits (even those not corresponding to a defined flag). + /// Convert from a bits value, without altering them in any way. fn from_bits_retain(bits: Self::Bits) -> Self; - /// Get the flag for a particular name. + /// Get a flags value with the bits of a flag with the given name set. + /// + /// This method will return `None` if `name` is empty or doesn't + /// correspond to any named flag. fn from_name(name: &str) -> Option { // Don't parse empty names as empty flags if name.is_empty() { @@ -99,29 +102,35 @@ pub trait Flags: Sized + 'static { None } - /// Iterate over enabled flag values. + /// Yield a set of contained flags values. + /// + /// Each yielded flags value will correspond to a defined named flag. Any unknown bits + /// will be yielded together as a final flags value. fn iter(&self) -> iter::Iter { iter::Iter::new(self) } - /// Iterate over the raw names and bits for enabled flag values. + /// Yield a set of contained named flags values. + /// + /// This method is like [`Flags::iter`], except only yields bits in contained named flags. + /// Any unknown bits, or bits not corresponding to a contained flag will not be yielded. fn iter_names(&self) -> iter::IterNames { iter::IterNames::new(self) } - /// Returns `true` if no flags are currently stored. + /// Whether all bits in this flags value are unset. fn is_empty(&self) -> bool { self.bits() == Self::Bits::EMPTY } - /// Returns `true` if all flags are currently set. + /// Whether all defined flags are contained in this flags value. fn is_all(&self) -> bool { // NOTE: We check against `Self::all` here, not `Self::Bits::ALL` // because the set of all flags may not use all bits Self::all().bits() | self.bits() == self.bits() } - /// Returns `true` if there are flags common to both `self` and `other`. + /// Whether any set bits in a source flags value are also set in a target flags value. fn intersects(&self, other: Self) -> bool where Self: Sized, @@ -129,7 +138,7 @@ pub trait Flags: Sized + 'static { self.bits() & other.bits() != Self::Bits::EMPTY } - /// Returns `true` if all of the flags in `other` are contained within `self`. + /// Whether all set bits in a source flags value are also set in a target flags value. fn contains(&self, other: Self) -> bool where Self: Sized, @@ -137,9 +146,7 @@ pub trait Flags: Sized + 'static { self.bits() & other.bits() == other.bits() } - /// Inserts the specified flags in-place. - /// - /// This method is equivalent to `union`. + /// The bitwise or (`|`) of the bits in two flags values. fn insert(&mut self, other: Self) where Self: Sized, @@ -147,9 +154,10 @@ pub trait Flags: Sized + 'static { *self = Self::from_bits_retain(self.bits()).union(other); } - /// Removes the specified flags in-place. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). /// - /// This method is equivalent to `difference`. + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `remove` won't truncate `other`, but the `!` operator will. fn remove(&mut self, other: Self) where Self: Sized, @@ -157,9 +165,7 @@ pub trait Flags: Sized + 'static { *self = Self::from_bits_retain(self.bits()).difference(other); } - /// Toggles the specified flags in-place. - /// - /// This method is equivalent to `symmetric_difference`. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. fn toggle(&mut self, other: Self) where Self: Sized, @@ -167,7 +173,7 @@ pub trait Flags: Sized + 'static { *self = Self::from_bits_retain(self.bits()).symmetric_difference(other); } - /// Inserts or removes the specified flags depending on the passed value. + /// Call [`Flags::insert`] when `value` is `true` or [`Flags::remove`] when `value` is `false`. fn set(&mut self, other: Self, value: bool) where Self: Sized, @@ -179,32 +185,34 @@ pub trait Flags: Sized + 'static { } } - /// Returns the intersection between the flags in `self` and `other`. + /// The bitwise and (`&`) of the bits in two flags values. #[must_use] fn intersection(self, other: Self) -> Self { Self::from_bits_retain(self.bits() & other.bits()) } - /// Returns the union of between the flags in `self` and `other`. + /// The bitwise or (`|`) of the bits in two flags values. #[must_use] fn union(self, other: Self) -> Self { Self::from_bits_retain(self.bits() | other.bits()) } - /// Returns the difference between the flags in `self` and `other`. + /// The intersection of a source flags value with the complement of a target flags value (`&!`). + /// + /// This method is not equivalent to `self & !other` when `other` has unknown bits set. + /// `difference` won't truncate `other`, but the `!` operator will. #[must_use] fn difference(self, other: Self) -> Self { Self::from_bits_retain(self.bits() & !other.bits()) } - /// Returns the symmetric difference between the flags - /// in `self` and `other`. + /// The bitwise exclusive-or (`^`) of the bits in two flags values. #[must_use] fn symmetric_difference(self, other: Self) -> Self { Self::from_bits_retain(self.bits() ^ other.bits()) } - /// Returns the complement of this set of flags. + /// The bitwise negation (`!`) of the bits in a flags value, truncating the result. #[must_use] fn complement(self) -> Self { Self::from_bits_truncate(!self.bits()) @@ -223,10 +231,10 @@ pub trait Bits: + Sized + 'static { - /// The value of `Self` where no bits are set. + /// A value with all bits unset. const EMPTY: Self; - /// The value of `Self` where all bits are set. + /// A value with all bits set. const ALL: Self; }