diff --git a/data-model/src/entry.rs b/data-model/src/entry.rs index f30a084..f9a433a 100644 --- a/data-model/src/entry.rs +++ b/data-model/src/entry.rs @@ -42,7 +42,7 @@ where S: SubspaceId, PD: PayloadDigest, { - /// Create a new [`Entry`]. + /// Creates a new [`Entry`]. pub fn new( namespace_id: N, subspace_id: S, @@ -61,38 +61,39 @@ where } } - /// Return a reference to the identifier of the namespace to which the [`Entry`] belongs. + /// Returns a reference to the identifier of the namespace to which the [`Entry`] belongs. pub fn namespace_id(&self) -> &N { &self.namespace_id } - /// Return a reference to the identifier of the subspace_id to which the [`Entry`] belongs. + /// Returns a reference to the identifier of the subspace_id to which the [`Entry`] belongs. pub fn subspace_id(&self) -> &S { &self.subspace_id } - /// Return a reference to the [`Path`] to which the [`Entry`] was written. + /// Returns a reference to the [`Path`] to which the [`Entry`] was written. pub fn path(&self) -> &Path { &self.path } - /// Return the claimed creation time of the [`Entry`]. + /// Returns the claimed creation time of the [`Entry`]. pub fn timestamp(&self) -> Timestamp { self.timestamp } - /// Return the length of the Payload in bytes. + /// Returns the length of the Payload in bytes. pub fn payload_length(&self) -> u64 { self.payload_length } - /// Return a reference to the result of applying hash_payload to the Payload. + /// Returns a reference to the result of applying hash_payload to the Payload. pub fn payload_digest(&self) -> &PD { &self.payload_digest } - /// Return if this [`Entry`] is newer than another using their timestamps. + /// Returns if this [`Entry`] is newer than another using their timestamps. /// Tie-breaks using the Entries' payload digest and payload length otherwise. + /// /// [Definition](https://willowprotocol.org/specs/data-model/index.html#entry_newer). pub fn is_newer_than(&self, other: &Self) -> bool { other.timestamp < self.timestamp @@ -293,7 +294,7 @@ where S: SubspaceId, PD: PayloadDigest, { - /// Construct an [`AuthorisedEntry`] if the token permits the writing of this entry, otherwise return an [`UnauthorisedWriteError`] + /// Returns an [`AuthorisedEntry`] if the token permits the writing of this entry, otherwise returns an [`UnauthorisedWriteError`] pub fn new( entry: Entry, @@ -309,8 +310,7 @@ where Err(UnauthorisedWriteError) } - /// Construct an [`AuthorisedEntry`] without checking if the token permits the writing of this - /// entry. + /// Returns an [`AuthorisedEntry`] without checking if the token permits the writing of this entry. /// /// Should only be used if the token was created by ourselves or previously validated. pub fn new_unchecked(entry: Entry, token: AT) -> Self @@ -320,17 +320,17 @@ where Self(entry, token) } - /// Split into [`Entry`] and [`AuthorisationToken`] halves. + /// Splits this into [`Entry`] and [`AuthorisationToken`] halves. pub fn into_parts(self) -> (Entry, AT) { (self.0, self.1) } - /// Get a reference to the [`Entry`]. + /// Gets a reference to the [`Entry`]. pub fn entry(&self) -> &Entry { &self.0 } - /// Get a reference to the [`AuthorisationToken`]. + /// Gets a reference to the [`AuthorisationToken`]. pub fn token(&self) -> &AT { &self.1 } diff --git a/data-model/src/grouping/area.rs b/data-model/src/grouping/area.rs index 21d0774..54a9c23 100644 --- a/data-model/src/grouping/area.rs +++ b/data-model/src/grouping/area.rs @@ -19,7 +19,7 @@ pub enum AreaSubspace { } impl AreaSubspace { - /// Return whether this [`AreaSubspace`] includes a given [`SubspaceId`]. + /// Returns whether this [`AreaSubspace`] includes a given [`SubspaceId`]. pub fn includes(&self, sub: &S) -> bool { match self { AreaSubspace::Any => true, @@ -27,7 +27,7 @@ impl AreaSubspace { } } - /// Return the intersection between two [`AreaSubspace`]. + /// Returns the intersection between two [`AreaSubspace`]. fn intersection(&self, other: &Self) -> Option { match (self, other) { (Self::Any, Self::Any) => Some(Self::Any), @@ -38,7 +38,7 @@ impl AreaSubspace { } } - /// Return whether this [`AreaSubspace`] includes Entries with arbitrary subspace_ids. + /// Returns whether this [`AreaSubspace`] includes Entries with arbitrary subspace_ids. pub fn is_any(&self) -> bool { matches!(self, AreaSubspace::Any) } @@ -75,7 +75,7 @@ pub struct Area Area { - /// Create a new [`Area`]. + /// Creates a new [`Area`]. pub fn new( subspace: AreaSubspace, path: Path, @@ -88,28 +88,29 @@ impl Area &AreaSubspace { &self.subspace } - /// Return a reference to the [`Path`]. + /// Returns a reference to the [`Path`]. /// /// To be included in this [`Area`], an [`Entry`]’s `path` must be prefixed by the path. pub fn path(&self) -> &Path { &self.path } - /// Return a reference to the range of [`Timestamp`]s. + /// Returns a reference to the range of [`Timestamp`]s. /// /// To be included in this [`Area`], an [`Entry`]’s `timestamp` must be included in the times. pub fn times(&self) -> &Range { &self.times } - /// Return an [`Area`] which includes all entries. + /// Returns an [`Area`] which includes all entries. + /// /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#full_area). pub fn new_full() -> Self { Self { @@ -119,7 +120,8 @@ impl Area Self { Self { @@ -129,7 +131,7 @@ impl Area( &self, entry: &Entry, @@ -139,7 +141,7 @@ impl Area bool { match (&self.subspace, &area.subspace) { (AreaSubspace::Any, AreaSubspace::Any) => { @@ -157,7 +159,8 @@ impl Area) -> Option { let subspace_id = self.subspace.intersection(&other.subspace)?; diff --git a/data-model/src/grouping/area_of_interest.rs b/data-model/src/grouping/area_of_interest.rs index 76cf07c..f0dbc10 100644 --- a/data-model/src/grouping/area_of_interest.rs +++ b/data-model/src/grouping/area_of_interest.rs @@ -25,7 +25,8 @@ impl } } - /// Return the intersection of this [`AreaOfInterest`] with another. + /// Returns the intersection of this [`AreaOfInterest`] with another. + /// /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#aoi_intersection). pub fn intersection( &self, diff --git a/data-model/src/grouping/range.rs b/data-model/src/grouping/range.rs index 16f9e7c..82e5493 100644 --- a/data-model/src/grouping/range.rs +++ b/data-model/src/grouping/range.rs @@ -152,12 +152,12 @@ impl Range where T: Ord + Clone, { - /// Construct a range. + /// Returns a new [`Range`]. pub fn new(start: T, end: RangeEnd) -> Self { Self { start, end } } - /// Construct a new [open range](https://willowprotocol.org/specs/grouping-entries/index.html#open_range) from a [start value](https://willowprotocol.org/specs/grouping-entries/index.html#start_value). + /// Returns a new [open range](https://willowprotocol.org/specs/grouping-entries/index.html#open_range) from a [start value](https://willowprotocol.org/specs/grouping-entries/index.html#start_value). pub fn new_open(start: T) -> Self { Self { start, @@ -165,7 +165,7 @@ where } } - /// Construct a new [closed range](https://willowprotocol.org/specs/grouping-entries/index.html#closed_range) from a [start](https://willowprotocol.org/specs/grouping-entries/index.html#start_value) and [end_value](https://willowprotocol.org/specs/grouping-entries/index.html#end_value), or [`None`] if the resulting range would never [include](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) any values. + /// Returns a new [closed range](https://willowprotocol.org/specs/grouping-entries/index.html#closed_range) from a [start](https://willowprotocol.org/specs/grouping-entries/index.html#start_value) and [end_value](https://willowprotocol.org/specs/grouping-entries/index.html#end_value), or [`None`] if the resulting range would never [include](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) any values. pub fn new_closed(start: T, end: T) -> Option { if start < end { return Some(Self { @@ -177,7 +177,7 @@ where None } - /// Return whether a given value is [included](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) by the [`Range`] or not. + /// Returns whether a given value is [included](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) by the [`Range`] or not. pub fn includes(&self, value: &T) -> bool { &self.start <= value && self.end.gt_val(value) } @@ -187,7 +187,7 @@ where self.start <= other.start && self.end >= other.end } - /// Create the [intersection](https://willowprotocol.org/specs/grouping-entries/index.html#range_intersection) between this [`Range`] and another `Range`. + /// Creates the [intersection](https://willowprotocol.org/specs/grouping-entries/index.html#range_intersection) between this [`Range`] and another `Range`, if any. pub fn intersection(&self, other: &Self) -> Option { let start = cmp::max(&self.start, &other.start); let end = match (&self.end, &other.end) { @@ -210,7 +210,7 @@ impl Range where T: Ord + Clone, { - /// Create a new range which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) everything. + /// Creates a new range which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#range_include) everything. pub fn full() -> Self { Self::new_open(T::default()) } diff --git a/data-model/src/grouping/range_3d.rs b/data-model/src/grouping/range_3d.rs index 59929fa..a874b99 100644 --- a/data-model/src/grouping/range_3d.rs +++ b/data-model/src/grouping/range_3d.rs @@ -26,7 +26,7 @@ pub struct Range3d Range3d { - /// Create a new [`Range3d`]. + /// Creates a new [`Range3d`]. pub fn new( subspaces: Range, paths: Range>, @@ -39,7 +39,7 @@ impl } } - /// Create a new [`Range3d`] that covers everything. + /// Creates a new [`Range3d`] that covers everything. pub fn new_full() -> Self { Self::new( Default::default(), @@ -48,25 +48,28 @@ impl ) } - /// Return a reference to the range of [`SubspaceId`]s. + /// Returns a reference to the range of [`SubspaceId`]s. + /// /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#SubspaceRange). pub fn subspaces(&self) -> &Range { &self.subspaces } - /// Return a reference to the range of [`Path`]s. + /// Returns a reference to the range of [`Path`]s. + /// /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#PathRange). pub fn paths(&self) -> &Range> { &self.paths } - /// Return a reference to the range of [`Timestamp`]s. + /// Returns a reference to the range of [`Timestamp`]s. + /// /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#TimeRange). pub fn times(&self) -> &Range { &self.times } - /// Return whether an [`Entry`] is [included](https://willowprotocol.org/specs/grouping-entries/index.html#d3_range_include) by this 3d range. + /// Returns whether an [`Entry`] is [included](https://willowprotocol.org/specs/grouping-entries/index.html#d3_range_include) by this 3d range. pub fn includes_entry( &self, entry: &Entry, @@ -76,7 +79,7 @@ impl && self.times.includes(&entry.timestamp()) } - /// Return the intersection between this [`Range3d`] and another. + /// Returns the intersection between this [`Range3d`] and another. pub fn intersection(&self, other: &Range3d) -> Option { let paths = self.paths.intersection(&other.paths)?; let times = self.times.intersection(&other.times)?; diff --git a/data-model/src/lengthy_entry.rs b/data-model/src/lengthy_entry.rs index 06fa898..71160d2 100644 --- a/data-model/src/lengthy_entry.rs +++ b/data-model/src/lengthy_entry.rs @@ -23,22 +23,22 @@ where S: SubspaceId, PD: PayloadDigest, { - /// Create a new lengthy entry from a given [`Entry`] and the number of consecutive bytes from the start of the entry’s payload that are held. + /// Returns a new lengthy entry from a given [`Entry`] and the number of consecutive bytes from the start of the entry’s payload that are held. pub fn new(entry: Entry, available: u64) -> Self { Self { entry, available } } - /// The entry in question. + /// Returns the entry in question. pub fn entry(&self) -> &Entry { &self.entry } - /// The number of consecutive bytes from the start of the entry’s Payload that the peer holds. + /// Returns the number of consecutive bytes from the start of the entry’s Payload that the peer holds. pub fn available(&self) -> u64 { self.available } - /// Turn this into a regular [`Entry`]. + /// Turns this into a regular [`Entry`]. pub fn into_entry(self) -> Entry { self.entry } @@ -86,22 +86,22 @@ where PD: PayloadDigest, AT: AuthorisationToken, { - /// Create a new lengthy entry from a given [`AuthorisedEntry`] and the number of consecutive bytes from the start of the entry’s payload that are held. + /// Returns a new lengthy entry from a given [`AuthorisedEntry`] and the number of consecutive bytes from the start of the entry’s payload that are held. pub fn new(entry: AuthorisedEntry, available: u64) -> Self { Self { entry, available } } - /// The entry in question. + /// Returns the authorised entry in question. pub fn entry(&self) -> &AuthorisedEntry { &self.entry } - /// The number of consecutive bytes from the start of the entry’s Payload that the peer holds. + /// Returns the number of consecutive bytes from the start of the entry’s Payload that the peer holds. pub fn available(&self) -> u64 { self.available } - /// Turn this into a [`AuthorisedEntry`]. + /// Turns this into a [`AuthorisedEntry`]. pub fn into_authorised_entry(self) -> AuthorisedEntry { self.entry } diff --git a/data-model/src/parameters.rs b/data-model/src/parameters.rs index 8a7c246..7e00e68 100644 --- a/data-model/src/parameters.rs +++ b/data-model/src/parameters.rs @@ -12,7 +12,8 @@ pub trait NamespaceId: Eq + Default + Clone {} /// /// The [`Default`] implementation **must** return the least element in the total order of [`SubspaceId`]. pub trait SubspaceId: Ord + Default + Clone { - /// Return the next possible value in the set of all [`SubspaceId`]. + /// Returns the next possible value in the set of all [`SubspaceId`]. + /// /// e.g. the successor of 3 is 4. fn successor(&self) -> Option; } @@ -37,6 +38,6 @@ pub trait AuthorisationToken< PD: PayloadDigest, > { - /// Determine whether this type (nominally a [`AuthorisationToken`](https://willowprotocol.org/specs/data-model/index.html#AuthorisationToken)) is able to prove write permission for a given [`Entry`]. + /// Determines whether this type (nominally a [`AuthorisationToken`](https://willowprotocol.org/specs/data-model/index.html#AuthorisationToken)) is able to prove write permission for a given [`Entry`]. fn is_authorised_write(&self, entry: &Entry) -> bool; } diff --git a/data-model/src/path.rs b/data-model/src/path.rs index 240576a..af69a02 100644 --- a/data-model/src/path.rs +++ b/data-model/src/path.rs @@ -21,7 +21,7 @@ use bytes::{BufMut, Bytes, BytesMut}; pub struct Component<'a, const MAX_COMPONENT_LENGTH: usize>(&'a [u8]); impl<'a, const MAX_COMPONENT_LENGTH: usize> Component<'a, MAX_COMPONENT_LENGTH> { - /// Create a `Component` from a byte slice. Return `None` if the slice is longer than `MaxComponentLength`. + /// Creates a `Component` from a byte slice. Return `None` if the slice is longer than `MaxComponentLength`. pub fn new(slice: &'a [u8]) -> Option { if slice.len() <= MAX_COMPONENT_LENGTH { return Some(unsafe { Self::new_unchecked(slice) }); // Safe because we just checked the length. @@ -30,7 +30,7 @@ impl<'a, const MAX_COMPONENT_LENGTH: usize> Component<'a, MAX_COMPONENT_LENGTH> } } - /// Create a `Component` from a byte slice, without verifying its length. + /// Creates a `Component` from a byte slice, without verifying its length. /// /// #### Safety /// @@ -40,7 +40,7 @@ impl<'a, const MAX_COMPONENT_LENGTH: usize> Component<'a, MAX_COMPONENT_LENGTH> Self(slice) } - /// Create an empty component. + /// Returns an empty component. pub fn new_empty() -> Self { Self(&[]) } @@ -77,7 +77,7 @@ impl<'a, const MAX_COMPONENT_LENGTH: usize> Borrow<[u8]> for Component<'a, MAX_C pub struct OwnedComponent(Bytes); impl OwnedComponent { - /// Create an `OwnedComponent` by copying data from a byte slice. Return `None` if the slice is longer than `MaxComponentLength`. + /// Creates an `OwnedComponent` by copying data from a byte slice. Return `None` if the slice is longer than `MaxComponentLength`. /// /// #### Complexity /// @@ -90,7 +90,7 @@ impl OwnedComponent { } } - /// Create an `OwnedComponent` by copying data from a byte slice, without verifying its length. + /// Creates an `OwnedComponent` by copying data from a byte slice, without verifying its length. /// /// #### Safety /// @@ -104,7 +104,7 @@ impl OwnedComponent { Self(Bytes::copy_from_slice(data)) } - /// Create an empty component. + /// Returns an empty component. /// /// #### Complexity /// @@ -177,7 +177,7 @@ pub struct Path { } impl Path { - /// Construct an empty path, i.e., a path of zero components. + /// Returns an empty path, i.e., a path of zero components. /// /// #### Complexity /// @@ -192,7 +192,7 @@ impl Path { } } - /// Construct a singleton path, i.e., a path of exactly one component. + /// Creates a singleton path, i.e., a path of exactly one component. /// /// Copies the bytes of the component into an owned allocation on the heap. /// @@ -217,7 +217,7 @@ impl Path { } } - /// Construct a path of known total length from an [`ExactSizeIterator`][core::iter::ExactSizeIterator] of components. + /// Creates a path of known total length from an [`ExactSizeIterator`][core::iter::ExactSizeIterator] of components. /// /// Copies the bytes of the components into an owned allocation on the heap. /// @@ -270,7 +270,7 @@ impl Path { }) } - /// Construct a path from a slice of components. + /// Creates a path from a slice of components. /// /// Copies the bytes of the components into an owned allocation on the heap. /// @@ -286,7 +286,7 @@ impl Path { return Self::new_from_iter(total_length, &mut components.iter().copied()); } - /// Construct a new path by appending a component to this one. + /// Creates a new path by appending a component to this one. /// /// Creates a fully separate copy of the new data on the heap; this function is not more efficient than constructing the new path from scratch. /// @@ -301,7 +301,7 @@ impl Path { ); } - /// Construct a new path by appending a slice of components to this one. + /// Creates a new path by appending a slice of components to this one. /// /// Creates a fully separate copy of the new data on the heap; this function is not more efficient than constructing the new path from scratch. /// @@ -320,7 +320,7 @@ impl Path { ); } - /// Get the number of components in this path. + /// Returns the number of components in this path. /// /// Guaranteed to be at most `MCC`. /// @@ -331,7 +331,7 @@ impl Path { self.component_count } - /// Return whether this path has zero components. + /// Returns whether this path has zero components. /// /// #### Complexity /// @@ -340,7 +340,7 @@ impl Path { self.get_component_count() == 0 } - /// Get the sum of the lengths of all components in this path. + /// Returns the sum of the lengths of all components in this path. /// /// Guaranteed to be at most `MCC`. /// @@ -359,7 +359,7 @@ impl Path { } } - /// Get the `i`-th [`Component`] of this path. + /// Returns the `i`-th [`Component`] of this path. /// /// #### Complexity /// @@ -368,7 +368,7 @@ impl Path { return HeapEncoding::::get_component(self.data.as_ref(), i); } - /// Get an owned handle to the `i`-th [`Component`] of this path. + /// Returns an owned handle to the `i`-th [`Component`] of this path. /// /// #### Complexity /// @@ -379,7 +379,7 @@ impl Path { Some(OwnedComponent(self.data.0.slice(start..end))) } - /// Create an iterator over the components of this path. + /// Creates an iterator over the components of this path. /// /// Stepping the iterator takes `O(1)` time and performs no memory allocations. /// @@ -393,7 +393,7 @@ impl Path { self.suffix_components(0) } - /// Create an iterator over the components of this path, starting at the `i`-th component. If `i` is greater than or equal to the number of components, the iterator yields zero items. + /// Creates an iterator over the components of this path, starting at the `i`-th component. If `i` is greater than or equal to the number of components, the iterator yields zero items. /// /// Stepping the iterator takes `O(1)` time and performs no memory allocations. /// @@ -410,7 +410,7 @@ impl Path { }) } - /// Create an iterator over owned handles to the components of this path. + /// Creates an iterator over owned handles to the components of this path. /// /// Stepping the iterator takes `O(1)` time and performs no memory allocations. /// @@ -425,7 +425,7 @@ impl Path { self.suffix_owned_components(0) } - /// Create an iterator over owned handles to the components of this path, starting at the `i`-th component. If `i` is greater than or equal to the number of components, the iterator yields zero items. + /// Creates an iterator over owned handles to the components of this path, starting at the `i`-th component. If `i` is greater than or equal to the number of components, the iterator yields zero items. /// /// Stepping the iterator takes `O(1)` time and performs no memory allocations. /// @@ -443,7 +443,7 @@ impl Path { }) } - /// Create a new path that consists of the first `length` components. More efficient than creating a new [`Path`] from scratch. + /// Creates a new path that consists of the first `length` components. More efficient than creating a new [`Path`] from scratch. /// /// Returns `None` if `length` is greater than `self.get_component_count()`. /// @@ -458,7 +458,7 @@ impl Path { } } - /// Create a new path that consists of the first `length` components. More efficient than creating a new [`Path`] from scratch. + /// Creates a new path that consists of the first `length` components. More efficient than creating a new [`Path`] from scratch. /// /// #### Safety /// @@ -475,7 +475,7 @@ impl Path { } } - /// Create an iterator over all prefixes of this path (including th empty path and the path itself). + /// Creates an iterator over all prefixes of this path (including th empty path and the path itself). /// /// Stepping the iterator takes `O(1)` time and performs no memory allocations. /// @@ -490,7 +490,7 @@ impl Path { }) } - /// Test whether this path is a prefix of the given path. + /// Tests whether this path is a prefix of the given path. /// Paths are always a prefix of themselves, and the empty path is a prefix of every path. /// /// #### Complexity @@ -506,7 +506,7 @@ impl Path { self.get_component_count() <= other.get_component_count() } - /// Test whether this path is prefixed by the given path. + /// Tests whether this path is prefixed by the given path. /// Paths are always a prefix of themselves. /// /// #### Complexity @@ -516,7 +516,7 @@ impl Path { other.is_prefix_of(self) } - /// Return the longest common prefix of this path and the given path. + /// Returns the longest common prefix of this path and the given path. /// /// #### Complexity /// @@ -535,7 +535,7 @@ impl Path { self.create_prefix(lcp_len).unwrap() // zip ensures that lcp_len <= self.get_component_count() } - /// Return the least path which is strictly greater than `self`, or return `None` if `self` is the greatest possible path. + /// Returns the least path which is strictly greater than `self`, or return `None` if `self` is the greatest possible path. /// /// #### Complexity /// @@ -594,7 +594,7 @@ impl Path { None } - /// Return the least path that is strictly greater than `self` and which is not prefixed by `self`, or `None` if no such path exists. + /// Returns the least path that is strictly greater than `self` and which is not prefixed by `self`, or `None` if no such path exists. /// /// #### Complexity /// @@ -693,7 +693,7 @@ impl PartialOrd for Path Ord for Path { fn cmp(&self, other: &Self) -> core::cmp::Ordering { return self.components().cmp(other.components()); @@ -1022,7 +1022,7 @@ fn fixed_width_increment(buf: &mut [u8]) { } } -/// Create a new BufMut that stores the heap encoding of the first i components of `original`, but increasing the length of the final component by `extra_capacity`. No data to fill that extra capacity is written into the buffer. +/// Creates a new BufMut that stores the heap encoding of the first i components of `original`, but increasing the length of the final component by `extra_capacity`. No data to fill that extra capacity is written into the buffer. fn clone_prefix_and_lengthen_final_component< const MCL: usize, const MCC: usize, @@ -1073,7 +1073,7 @@ impl ScratchSpacePathDecoding { } } - /// Panic if i >= MCC. + /// Panics if i >= MCC. pub fn set_component_accumulated_length( &mut self, component_accumulated_length: usize, @@ -1102,7 +1102,7 @@ impl ScratchSpacePathDecoding { self.component_accumulated_lengths[i] } - /// Return a slice of the accumulated component lengths up to but excluding the `i`-th component, encoded as native-endian u8s. + /// Returns a slice of the accumulated component lengths up to but excluding the `i`-th component, encoded as native-endian u8s. /// /// # Safety /// @@ -1114,7 +1114,7 @@ impl ScratchSpacePathDecoding { ) } - /// Return a mutable slice of the i-th path_data. + /// Returns a mutable slice of the i-th path_data. /// /// # Safety /// @@ -1129,7 +1129,7 @@ impl ScratchSpacePathDecoding { &mut self.path_data[start..end] } - /// Return a mutable slice of the path_data up to but excluding the i-th component. + /// Returns a mutable slice of the path_data up to but excluding the i-th component. /// /// # Safety /// @@ -1139,7 +1139,7 @@ impl ScratchSpacePathDecoding { &mut self.path_data[0..end] } - /// Get the path data of the first `i` components. + /// Returns the path data of the first `i` components. /// /// # Safety /// @@ -1154,7 +1154,7 @@ impl ScratchSpacePathDecoding { &self.path_data[..end] } - /// Copy the data from this struct into a new Path of `i` components. + /// Copies the data from this struct into a new Path of `i` components. /// /// # Safety /// diff --git a/data-model/src/relative_encodings.rs b/data-model/src/relative_encodings.rs index 29728b6..d711239 100644 --- a/data-model/src/relative_encodings.rs +++ b/data-model/src/relative_encodings.rs @@ -36,7 +36,7 @@ pub(super) mod encoding { impl RelativeEncodable> for Path { - /// Encode a path relative to another path. + /// Encodes this [`Path`] relative to a reference [`Path`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_path_relative) async fn relative_encode( @@ -70,7 +70,7 @@ pub(super) mod encoding { impl RelativeDecodable> for Path { - /// Decode a path relative to this path. + /// Decodes a [`Path`] relative to a reference [`Path`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_path_relative) async fn relative_decode( @@ -182,7 +182,7 @@ pub(super) mod encoding { S: SubspaceId + Encodable, PD: PayloadDigest + Encodable, { - /// Encode an [`Entry`] relative to a reference [`Entry`]. + /// Encodes this [`Entry`] relative to a reference [`Entry`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_etry_relative_entry). async fn relative_encode( @@ -244,7 +244,7 @@ pub(super) mod encoding { S: SubspaceId + Decodable + std::fmt::Debug, PD: PayloadDigest + Decodable, { - /// Decode an [`Entry`] relative from this [`Entry`]. + /// Decodes an [`Entry`] relative to the given reference [`Entry`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_etry_relative_entry). async fn relative_decode( @@ -344,7 +344,7 @@ pub(super) mod encoding { S: SubspaceId + Encodable, PD: PayloadDigest + Encodable, { - /// Encode an [`Entry`] relative to a reference [`NamespaceId`] and [`Area`]. + /// Encodes this [`Entry`] relative to a reference [`NamespaceId`] and [`Area`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_entry_in_namespace_area). async fn relative_encode( @@ -407,7 +407,7 @@ pub(super) mod encoding { S: SubspaceId + Decodable + std::fmt::Debug, PD: PayloadDigest + Decodable, { - /// Decode an [`Entry`] relative to a reference [`NamespaceId`] and [`Area`]. + /// Decodes an [`Entry`] relative to a reference [`NamespaceId`] and [`Area`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_entry_in_namespace_area). async fn relative_decode( @@ -494,7 +494,7 @@ pub(super) mod encoding { S: SubspaceId + Encodable, PD: PayloadDigest + Encodable, { - /// Encode an [`Entry`] relative to a reference [`NamespaceId`] and [`Range3d`]. + /// Encodes this [`Entry`] relative to a reference [`NamespaceId`] and [`Range3d`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_entry_in_namespace_3drange). async fn relative_encode( @@ -595,7 +595,7 @@ pub(super) mod encoding { S: SubspaceId + Decodable + std::fmt::Debug, PD: PayloadDigest + Decodable, { - /// Decode an [`Entry`] relative to a reference [`NamespaceId`] and [`Range3d`]. + /// Decodes an [`Entry`] relative to a reference [`NamespaceId`] and [`Range3d`]. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_entry_in_namespace_3drange). async fn relative_decode( @@ -732,7 +732,7 @@ pub(super) mod encoding { where S: SubspaceId + Encodable, { - /// Encode an [`Area`] relative to another [`Area`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. + /// Encodes this [`Area`] relative to another [`Area`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_area_in_area). async fn relative_encode( @@ -812,7 +812,7 @@ pub(super) mod encoding { where S: SubspaceId + Decodable, { - /// Decode an [`Area`] relative to another [`Area`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. + /// Decodes an [`Area`] relative to another [`Area`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_area_in_area). async fn relative_decode( @@ -980,7 +980,7 @@ pub(super) mod encoding { where S: SubspaceId + Encodable + std::fmt::Debug, { - /// Encode an [`Range3d`] relative to another [`Range3d`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. + /// Encodes this [`Range3d`] relative to another [`Range3d`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_area_in_area). async fn relative_encode( @@ -1171,7 +1171,7 @@ pub(super) mod encoding { where S: SubspaceId + Decodable + std::fmt::Debug, { - /// Encode an [`Range3d`] relative to another [`Range3d`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. + /// Decodes a [`Range3d`] relative to another [`Range3d`] which [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) it. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#enc_area_in_area). async fn relative_decode( diff --git a/data-model/src/store.rs b/data-model/src/store.rs index 6a671e1..0bbb895 100644 --- a/data-model/src/store.rs +++ b/data-model/src/store.rs @@ -162,7 +162,7 @@ impl< { } -/// Return when a payload is successfully appended to the [`Store`]. +/// Returned when a payload is successfully appended to the [`Store`]. #[derive(Debug, Clone)] pub enum PayloadAppendSuccess where @@ -364,10 +364,11 @@ where type BulkIngestionError: Display + Error; type OperationsError: Display + Error; - /// The [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) which all of this store's [`AuthorisedEntry`] belong to. + /// Returns the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) which all of this store's [`AuthorisedEntry`] belong to. fn namespace_id() -> N; - /// Attempt to ingest an [`AuthorisedEntry`] into the [`Store`]. + /// Attempts to ingest an [`AuthorisedEntry`] into the [`Store`]. + /// /// Will fail if the entry belonged to a different namespace than the store's, or if the `prevent_pruning` param is `true` and an ingestion would have triggered [prefix pruning](https://willowprotocol.org/specs/data-model/index.html#prefix_pruning). fn ingest_entry( &self, @@ -380,7 +381,7 @@ where >, >; - /// Attempt to ingest many [`AuthorisedEntry`] in the [`Store`]. + /// Attempts to ingest many [`AuthorisedEntry`] in the [`Store`]. /// /// The result being `Ok` does **not** indicate that all entry ingestions were successful, only that each entry had an ingestion attempt, some of which *may* have returned [`EntryIngestionError`]. The `Err` type of this result is only returned if there was some internal error. fn bulk_ingest_entry( @@ -404,7 +405,7 @@ where >, >; - /// Attempt to append part of a payload for a given [`AuthorisedEntry`]. + /// Attempts to append part of a payload for a given [`AuthorisedEntry`]. /// /// Will fail if: /// - The payload digest is not referred to by any of the store's entries. @@ -428,7 +429,7 @@ where where Producer: BulkProducer; - /// Locally forget an entry with a given [`Path`] and [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace) id, returning the forgotten entry, or an error if no entry with that path and subspace ID are held by this store. + /// Locally forgets an entry with a given [`Path`] and [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace) id, returning the forgotten entry, or an error if no entry with that path and subspace ID are held by this store. /// /// If the `traceless` parameter is `true`, the store will keep no record of ever having had the entry. If `false`, it *may* persist what was forgotten for an arbitrary amount of time. /// @@ -440,7 +441,7 @@ where traceless: bool, ) -> impl Future>; - /// Locally forget all [`AuthorisedEntry`] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all forgotten entries + /// Locally forgets all [`AuthorisedEntry`] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all forgotten entries /// /// If `protected` is `Some`, then all entries [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by that [`Area`] will be prevented from being forgotten, even though they are included by `area`. /// @@ -454,7 +455,7 @@ where traceless: bool, ) -> impl Future>>; - /// Locally forget the corresponding payload of the entry with a given path and subspace, or an error if no entry with that path and subspace ID is held by this store or if the entry's payload corresponds to other entries. + /// Locally forgets the corresponding payload of the entry with a given path and subspace, or an error if no entry with that path and subspace ID is held by this store or if the entry's payload corresponds to other entries. /// /// If the `traceless` parameter is `true`, the store will keep no record of ever having had the payload. If `false`, it *may* persist what was forgetten for an arbitrary amount of time. /// @@ -465,7 +466,7 @@ where traceless: bool, ) -> impl Future>; - /// Locally forget the corresponding payload of the entry with a given path and subspace, or an error if no entry with that path and subspace ID is held by this store. **The payload will be forgotten even if it corresponds to other entries**. + /// Locally forgets the corresponding payload of the entry with a given path and subspace, or an error if no entry with that path and subspace ID is held by this store. **The payload will be forgotten even if it corresponds to other entries**. /// /// If the `traceless` parameter is `true`, the store will keep no record of ever having had the payload. If `false`, it *may* persist what was forgetten for an arbitrary amount of time. /// @@ -476,7 +477,7 @@ where traceless: bool, ) -> impl Future>; - /// Locally forget all payloads with corresponding ['AuthorisedEntry'] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all [`PayloadDigest`] of forgotten payloads. Payloads corresponding to entries *outside* of the given `area` param will be be prevented from being forgotten. + /// Locally forgets all payloads with corresponding ['AuthorisedEntry'] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all [`PayloadDigest`] of forgotten payloads. Payloads corresponding to entries *outside* of the given `area` param will be be prevented from being forgotten. /// /// If `protected` is `Some`, then all payloads corresponding to entries [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by that [`Area`] will be prevented from being forgotten, even though they are included by `area`. /// @@ -490,7 +491,7 @@ where traceless: bool, ) -> impl Future>; - /// Locally forget all payloads with corresponding ['AuthorisedEntry'] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all [`PayloadDigest`] of forgotten payloads. **Payloads will be forgotten even if it corresponds to other entries outside the given area**. + /// Locally forgets all payloads with corresponding ['AuthorisedEntry'] [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by a given [`AreaOfInterest`], returning all [`PayloadDigest`] of forgotten payloads. **Payloads will be forgotten even if it corresponds to other entries outside the given area**. /// /// If `protected` is `Some`, then all payloads corresponding to entries [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by that [`Area`] will be prevented from being forgotten, even though they are included by `area`. /// @@ -504,10 +505,10 @@ where traceless: bool, ) -> impl Future>; - /// Force persistence of all previous mutations + /// Forces persistence of all previous mutations fn flush() -> impl Future>; - /// Return a [`LengthyAuthorisedEntry`] with the given [`Path`] and [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace) ID, if present. + /// Returns a [`LengthyAuthorisedEntry`] with the given [`Path`] and [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace) ID, if present. fn entry( &self, path: &Path, @@ -515,7 +516,7 @@ where ignore: Option, ) -> impl Future>; - /// Query which entries are [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by an [`AreaOfInterest`], returning a producer of [`LengthyAuthorisedEntry`]. + /// Queries which entries are [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by an [`AreaOfInterest`], returning a producer of [`LengthyAuthorisedEntry`]. fn query_area( &self, area: &AreaOfInterest, @@ -524,14 +525,14 @@ where ignore: Option, ) -> impl Producer>; - /// Subscribe to events concerning entries [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by an [`AreaOfInterest`], returning a producer of `StoreEvent`s which occurred since the moment of calling this function. + /// Subscribes to events concerning entries [included](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) by an [`AreaOfInterest`], returning a producer of `StoreEvent`s which occurred since the moment of calling this function. fn subscribe_area( &self, area: &Area, ignore: Option, ) -> impl Producer>; - /// Attempt to resume a subscription using a *progress ID* obtained from a previous subscription, or return an error if this store implementation is unable to resume the subscription. + /// Attempts to resume a subscription using a *progress ID* obtained from a previous subscription, or return an error if this store implementation is unable to resume the subscription. fn resume_subscription( &self, progress_id: u64, diff --git a/encoding/src/bytes.rs b/encoding/src/bytes.rs index 86e3d13..bf6fca2 100644 --- a/encoding/src/bytes.rs +++ b/encoding/src/bytes.rs @@ -12,7 +12,7 @@ pub mod encoding { #[syncify_replace(use ufotofu::sync::BulkProducer;)] use ufotofu::local_nb::BulkProducer; - /// Have `Producer` produce a single byte, or return an error if the final value was produced or the producer experienced an error. + /// Produces a single byte from the given `producer`, or return an error if the final value was produced or the producer experienced an error. pub async fn produce_byte( producer: &mut Producer, ) -> Result> @@ -27,7 +27,7 @@ pub mod encoding { } } -/// Return whether a bit at the given position is `1` or not. +/// Returns whether a bit at the given position is `1` or not. pub fn is_bitflagged(byte: u8, position: u8) -> bool { let mask = match position { 0 => 0b1000_0000, diff --git a/encoding/src/compact_width.rs b/encoding/src/compact_width.rs index 8e7fc75..38f559e 100644 --- a/encoding/src/compact_width.rs +++ b/encoding/src/compact_width.rs @@ -30,7 +30,7 @@ impl core::fmt::Display for NotACompactWidthError { impl std::error::Error for NotACompactWidthError {} impl CompactWidth { - /// Return a new [`CompactWidth`]. + /// Returns a new [`CompactWidth`]. pub(crate) fn new(n: u8) -> Result { match n { 1 => Ok(CompactWidth::One), @@ -41,7 +41,7 @@ impl CompactWidth { } } - /// Return the most compact width in bytes (1, 2, 4, or 8) needed to represent a given `u64` as a corresponding 8-bit, 16-bit, 32-bit, or 64-bit number. + /// Returns the most compact width in bytes (1, 2, 4, or 8) needed to represent a given `u64` as a corresponding 8-bit, 16-bit, 32-bit, or 64-bit number. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#compact_width). pub fn from_u64(value: u64) -> Self { @@ -56,7 +56,7 @@ impl CompactWidth { } } - /// Return the most compact width in bytes (1, 2, 4) needed to represent a given `u32` as a corresponding 8-bit, 16-bit, or 32-bit number. + /// Returns the most compact width in bytes (1, 2, 4) needed to represent a given `u32` as a corresponding 8-bit, 16-bit, or 32-bit number. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#compact_width). pub fn from_u32(value: u32) -> Self { @@ -69,7 +69,7 @@ impl CompactWidth { } } - /// Return the most compact width in bytes (1 or 2) needed to represent a given `u16` as a corresponding 8-bit or 16-bit number. + /// Returns the most compact width in bytes (1 or 2) needed to represent a given `u16` as a corresponding 8-bit or 16-bit number. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#compact_width). pub fn from_u16(value: u16) -> Self { @@ -80,14 +80,14 @@ impl CompactWidth { } } - /// Return [`CompactWidth::One`], the only [`CompactWidth`] needed to represent a given `u8`. + /// Returns [`CompactWidth::One`], the only [`CompactWidth`] needed to represent a given `u8`. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#compact_width). pub fn from_u8(_: u8) -> Self { CompactWidth::One } - /// Return the width in bytes of this [`CompactWidth`]. + /// Returns the width in bytes of this [`CompactWidth`]. pub fn width(&self) -> usize { match self { CompactWidth::One => 1, @@ -97,7 +97,7 @@ impl CompactWidth { } } - /// Encode a [`CompactWidth`] as a 2-bit integer `n` such that 2^n gives the bytewidth of the [`CompactWidth`], and then place that 2-bit number into a `u8` at the bit-index of `position`. + /// Encodes a [`CompactWidth`] as a 2-bit integer `n` such that 2^n gives the bytewidth of the [`CompactWidth`], and then place that 2-bit number into a `u8` at the bit-index of `position`. pub fn bitmask(&self, position: u8) -> u8 { let og = match self { CompactWidth::One => 0b0000_0000, @@ -133,7 +133,7 @@ pub mod encoding { #[syncify_replace(use crate::sync::{Decodable};)] use crate::Decodable; - /// Encode a `u64` integer as a `compact_width(value)`-byte big-endian integer, and consume that with a [`BulkConsumer`]. + /// Encodes a `u64` integer as a `compact_width(value)`-byte big-endian integer, and consume that with a [`BulkConsumer`]. pub async fn encode_compact_width_be>( value: u64, consumer: &mut Consumer, @@ -148,7 +148,7 @@ pub mod encoding { Ok(()) } - /// Decode the bytes representing a [`CompactWidth`]-bytes integer into a `usize`. + /// Decodes the bytes representing a [`CompactWidth`]-bytes integer into a `usize`. pub async fn decode_compact_width_be>( compact_width: CompactWidth, producer: &mut Producer, diff --git a/encoding/src/max_power.rs b/encoding/src/max_power.rs index aa63e51..d3c6e93 100644 --- a/encoding/src/max_power.rs +++ b/encoding/src/max_power.rs @@ -1,7 +1,7 @@ use syncify::syncify; use syncify::syncify_replace; -/// Return the least natural number such that 256^`n` is greater than or equal to `n`. +/// Returns the least natural number such that 256^`n` is greater than or equal to `n`. /// /// Used for determining the minimal number of bytes needed to represent a given unsigned integer, and more specifically [`path_length_power`](https://willowprotocol.org/specs/encodings/index.html#path_length_power) and [`path_count_power`](https://willowprotocol.org/specs/encodings/index.html#path_count_power). pub const fn max_power(max_size: u64) -> u8 { @@ -35,7 +35,7 @@ pub(super) mod encoding { #[syncify_replace(use ufotofu::sync::{BulkConsumer, BulkProducer};)] use ufotofu::local_nb::{BulkConsumer, BulkProducer}; - /// Encode a `usize` to a `n`-width unsigned integer, where `n` is the least number of bytes needed to represent `max_size`. + /// Encodes a `usize` to a `n`-width unsigned integer, where `n` is the least number of bytes needed to represent `max_size`. pub async fn encode_max_power( value: usize, max_size: usize, @@ -59,7 +59,7 @@ pub(super) mod encoding { Ok(()) } - /// Decode a `u64` from `n`-width bytestring, where `n` is the least number of bytes needed to represent `max_size`. + /// Decodes a `u64` from `n`-width bytestring, where `n` is the least number of bytes needed to represent `max_size`. pub async fn decode_max_power

( max_size: usize, producer: &mut P, diff --git a/meadowcap/src/communal_capability.rs b/meadowcap/src/communal_capability.rs index 9b2f227..9a23c25 100644 --- a/meadowcap/src/communal_capability.rs +++ b/meadowcap/src/communal_capability.rs @@ -23,7 +23,7 @@ impl std::error::Error { } -/// A capability that implements [communal namespaces](https://willowprotocol.org/specs/meadowcap/index.html#communal_namespace). +/// A capability which implements [communal namespaces](https://willowprotocol.org/specs/meadowcap/index.html#communal_namespace). /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#communal_capabilities). #[derive(Clone, Debug, PartialEq, Eq, Hash)] @@ -58,7 +58,7 @@ where UserPublicKey: SubspaceId + Encodable + Verifier, UserSignature: Encodable + Clone, { - /// Create a new communal capability granting access to the [`SubspaceId`] corresponding to the given `UserPublicKey`. + /// Creates a new communal capability granting access to the [`SubspaceId`] corresponding to the given `UserPublicKey`. pub fn new( namespace_key: NamespacePublicKey, user_key: UserPublicKey, @@ -76,7 +76,7 @@ where }) } - /// Delegate this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. + /// Delegates this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. /// Will fail if the area is not included by this capability's [granted area](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_granted_area), or if the given secret key does not correspond to the capability's [receiver](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_receiver). pub fn delegate( &self, @@ -121,7 +121,7 @@ where }) } - /// Append an existing delegation to an existing capability, or return an error if the delegation is invalid. + /// Appends an existing delegation to an existing capability, or return an error if the delegation is invalid. pub fn append_existing_delegation( &mut self, delegation: Delegation, @@ -154,14 +154,14 @@ where Ok(()) } - /// The kind of access this capability grants. + /// Returns the kind of access this capability grants. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_mode) pub fn access_mode(&self) -> AccessMode { self.access_mode } - /// The user to whom this capability grants access. + /// Returns the public key of the user to whom this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_receiver) pub fn receiver(&self) -> &UserPublicKey { @@ -176,14 +176,14 @@ where receiver } - /// The [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. + /// Returns the public key of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_granted_namespace) pub fn granted_namespace(&self) -> &NamespacePublicKey { &self.namespace_key } - /// The [`Area`] for which this capability grants access. + /// Returns the [`Area`] for which this capability grants access. /// /// [Definition](`https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_granted_area`) pub fn granted_area(&self) -> Area { @@ -197,14 +197,14 @@ where last_delegation.area().clone() } - /// Return a slice of all [`Delegation`]s made to this capability, with a concrete return type. + /// Returns a slice of all [`Delegation`]s made to this capability, with a concrete return type. pub(crate) fn delegations_( &self, ) -> core::slice::Iter> { self.delegations.iter() } - /// Return a slice of all [`Delegation`]s made to this capability. + /// Returns a slice of all [`Delegation`]s made to this capability. pub fn delegations( &self, ) -> impl ExactSizeIterator> @@ -212,17 +212,17 @@ where self.delegations_() } - /// Return the number of delegations present on this capability. + /// Returns the number of delegations present on this capability. pub fn delegations_len(&self) -> usize { self.delegations.len() } - /// Return the public key of the very first user this capability was issued to. + /// Returns the public key of the very first user this capability was issued to. pub fn progenitor(&self) -> &UserPublicKey { &self.user_key } - /// A bytestring to be signed for a new [`Delegation`]. + /// Returns a bytestring to be signed for a new [`Delegation`]. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#communal_handover) fn handover( diff --git a/meadowcap/src/mc_authorisation_token.rs b/meadowcap/src/mc_authorisation_token.rs index 527b6b6..d9bdc0c 100644 --- a/meadowcap/src/mc_authorisation_token.rs +++ b/meadowcap/src/mc_authorisation_token.rs @@ -61,6 +61,9 @@ where NamespaceSignature: Encodable + Clone, UserSignature: Encodable + Clone, { + /// Returns a new [`McAuthorisationToken`] using the given [`McCapability`] and [`UserSignature`]. + /// + /// Does **not** verify the signature's validity. pub fn new( capability: McCapability< MCL, diff --git a/meadowcap/src/mc_capability.rs b/meadowcap/src/mc_capability.rs index 526b20b..67ebbd6 100644 --- a/meadowcap/src/mc_capability.rs +++ b/meadowcap/src/mc_capability.rs @@ -85,7 +85,7 @@ where NamespaceSignature: Encodable + Clone, UserSignature: Encodable + Clone, { - /// Create a new communal capability granting access to the [`SubspaceId`] corresponding to the given `UserPublicKey`, or return an error if the namespace key is not communal. + /// Creates a new communal capability granting access to the [`SubspaceId`] corresponding to the given `UserPublicKey`, or return an error if the namespace key is not communal. pub fn new_communal( namespace_key: NamespacePublicKey, user_key: UserPublicKey, @@ -95,7 +95,7 @@ where Ok(Self::Communal(cap)) } - /// Create a new owned capability granting access to the [full area](https://willowprotocol.org/specs/grouping-entries/index.html#full_area) of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) to the given `UserPublicKey`. + /// Creates a new owned capability granting access to the [full area](https://willowprotocol.org/specs/grouping-entries/index.html#full_area) of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) to the given `UserPublicKey`. pub fn new_owned( namespace_key: NamespacePublicKey, namespace_secret: &NamespaceSecret, @@ -110,7 +110,7 @@ where Ok(Self::Owned(cap)) } - /// The kind of access this capability grants. + /// Returns the kind of access this capability grants. pub fn access_mode(&self) -> AccessMode { match self { Self::Communal(cap) => cap.access_mode(), @@ -118,7 +118,7 @@ where } } - /// The user to whom this capability grants access. + /// Returns the public key of the user to whom this capability grants access. pub fn receiver(&self) -> &UserPublicKey { match self { Self::Communal(cap) => cap.receiver(), @@ -126,7 +126,7 @@ where } } - /// The [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. + /// Returns the public key of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. pub fn granted_namespace(&self) -> &NamespacePublicKey { match self { Self::Communal(cap) => cap.granted_namespace(), @@ -134,7 +134,7 @@ where } } - /// The [`Area`] for which this capability grants access. + /// Returns the [`Area`] for which this capability grants access. pub fn granted_area(&self) -> Area { match self { Self::Communal(cap) => cap.granted_area(), @@ -142,7 +142,7 @@ where } } - /// Return a slice of all [`Delegation`]s made to this capability. + /// Returns a slice of all [`Delegation`]s made to this capability. pub fn delegations( &self, ) -> impl ExactSizeIterator> @@ -153,7 +153,7 @@ where } } - /// Return the number of delegations present on this capability. + /// Returns the number of delegations present on this capability. pub fn delegations_len(&self) -> usize { match self { McCapability::Communal(cap) => cap.delegations_len(), @@ -161,7 +161,7 @@ where } } - /// Return the public key of the very first user this capability was issued to. + /// Returns the public key of the very first user this capability was issued to. pub fn progenitor(&self) -> &UserPublicKey { match self { McCapability::Communal(cap) => cap.progenitor(), @@ -169,7 +169,7 @@ where } } - /// Delegate this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. + /// Delegates this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. /// Will fail if the area is not included by this capability's granted area, or if the given secret key does not correspond to the capability's receiver. pub fn delegate( &self, @@ -196,7 +196,7 @@ where Ok(delegated) } - /// Append an existing delegation to an existing capability, or return an error if the delegation is invalid. + /// Appends an existing delegation to an existing capability, or return an error if the delegation is invalid. pub fn append_existing_delegation( &mut self, delegation: Delegation, @@ -207,7 +207,7 @@ where } } - /// Return a new AuthorisationToken without checking if the resulting signature is correct (e.g. because you are going to immediately do that by constructing an [`willow_data_model::AuthorisedEntry`]). + /// Returns a new AuthorisationToken without checking if the resulting signature is correct (e.g. because you are going to immediately do that by constructing an [`willow_data_model::AuthorisedEntry`]). /// /// ## Safety /// @@ -248,7 +248,7 @@ where } } - /// Return a new [`McAuthorisationToken`], or an error if the resulting signature was not for the capability's receiver. + /// Returns a new [`McAuthorisationToken`], or an error if the resulting signature was not for the capability's receiver. pub fn authorisation_token( &self, entry: &Entry, diff --git a/meadowcap/src/mc_subspace_capability.rs b/meadowcap/src/mc_subspace_capability.rs index 2b41f66..ec2e7fa 100644 --- a/meadowcap/src/mc_subspace_capability.rs +++ b/meadowcap/src/mc_subspace_capability.rs @@ -68,7 +68,7 @@ where UserPublicKey: SubspaceId + Encodable + Verifier, UserSignature: Encodable + Clone, { - /// Generate a new [`McSubspaceCapability`] for a given user, or return an error if the given namespace secret is incorrect. + /// Creates a new [`McSubspaceCapability`] for a given user, or return an error if the given namespace secret is incorrect. pub fn new( namespace_key: NamespacePublicKey, namespace_secret: &NamespaceSecret, @@ -99,7 +99,7 @@ where }) } - /// Instantiate an [`McSubspaceCapability`] using an existing authorisation (e.g. one received over the network), or return an error if the signature was not created by the namespace key. + /// Creates an [`McSubspaceCapability`] using an existing authorisation (e.g. one received over the network), or return an error if the signature was not created by the namespace key. pub fn from_existing( namespace_key: NamespacePublicKey, user_key: UserPublicKey, @@ -122,7 +122,7 @@ where }) } - /// The user to whom this capability grants access. + /// Returns the public key of the user to whom this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#owned_cap_receiver) pub fn receiver(&self) -> &UserPublicKey { @@ -135,14 +135,14 @@ where last_delegation.user() } - /// The [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. + /// Returns the public key of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/pai/index.html#subspace_cap_receiver) pub fn granted_namespace(&self) -> &NamespacePublicKey { &self.namespace_key } - /// Delegate this subspace capability to a new `UserPublicKey`. + /// Delegates this subspace capability to a new `UserPublicKey`. /// Will fail if the given secret key does not correspond to the subspace capability's [receiver](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_receiver). pub fn delegate( &self, @@ -171,7 +171,7 @@ where }) } - /// Append an existing delegation to an existing capability, or return an error if the delegation is invalid. + /// Appends an existing delegation to an existing capability, or return an error if the delegation is invalid. pub fn append_existing_delegation( &mut self, delegation: SubspaceDelegation, @@ -190,14 +190,14 @@ where Ok(()) } - /// Return a slice of all [`SubspaceDelegation`]s made to this capability. + /// Returns a slice of all [`SubspaceDelegation`]s made to this capability. pub fn delegations( &self, ) -> impl Iterator> { self.delegations.iter() } - /// A bytestring to be signed for a new subspace capability delegation. + /// Returns a bytestring to be signed for a new subspace capability delegation. /// /// [Definition](https://willowprotocol.org/specs/pai/index.html#subspace_handover) fn handover(&self, new_user: &UserPublicKey) -> Box<[u8]> { diff --git a/meadowcap/src/owned_capability.rs b/meadowcap/src/owned_capability.rs index 9418add..0c06dbd 100644 --- a/meadowcap/src/owned_capability.rs +++ b/meadowcap/src/owned_capability.rs @@ -86,7 +86,7 @@ where UserPublicKey: SubspaceId + Encodable + Verifier, UserSignature: Encodable + Clone, { - /// Create a new owned capability granting access to the [full area](https://willowprotocol.org/specs/grouping-entries/index.html#full_area) of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) to the given `UserPublicKey`. + /// Creates a new owned capability granting access to the [full area](https://willowprotocol.org/specs/grouping-entries/index.html#full_area) of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) to the given `UserPublicKey`. pub fn new( namespace_key: NamespacePublicKey, namespace_secret: &NamespaceSecret, @@ -129,7 +129,7 @@ where }) } - /// Instantiate an [`OwnedCapability`] using an existing authorisation (e.g. one received over the network), or return an error if the signature was not created by the namespace key. + /// Creates an [`OwnedCapability`] using an existing authorisation (e.g. one received over the network), or return an error if the signature was not created by the namespace key. pub fn from_existing( namespace_key: NamespacePublicKey, user_key: UserPublicKey, @@ -162,7 +162,7 @@ where }) } - /// Delegate this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. + /// Delegates this capability to a new `UserPublicKey` for a given [`willow_data_model::grouping::Area`]. /// Will fail if the area is not included by this capability's [granted area](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_granted_area), or if the given secret key does not correspond to the capability's [receiver](https://willowprotocol.org/specs/meadowcap/index.html#communal_cap_receiver). pub fn delegate( &self, @@ -208,7 +208,7 @@ where }) } - /// Return whether this capability needs a complementing [`crate::McSubspaceCapability`] [(definition)](https://willowprotocol.org/specs/pai/index.html#subspace_capability) to in order to be fully authorised by the Willow General Sync Protocol. + /// Returns whether this capability needs a complementing [`crate::McSubspaceCapability`] [(definition)](https://willowprotocol.org/specs/pai/index.html#subspace_capability) to in order to be fully authorised by the Willow General Sync Protocol. pub fn needs_subspace_cap(&self) -> bool { if self.access_mode == AccessMode::Write { return false; @@ -227,7 +227,7 @@ where true } - /// Append an existing delegation to an existing capability, or return an error if the delegation is invalid. + /// Appends an existing delegation to an existing capability, or return an error if the delegation is invalid. pub fn append_existing_delegation( &mut self, delegation: Delegation, @@ -260,14 +260,14 @@ where Ok(()) } - /// The kind of access this capability grants. + /// Returns the kind of access this capability grants. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#owned_cap_mode) pub fn access_mode(&self) -> AccessMode { self.access_mode } - /// The user to whom this capability grants access. + /// Returns the public key of the user to whom this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#owned_cap_receiver) pub fn receiver(&self) -> &UserPublicKey { @@ -282,14 +282,14 @@ where receiver } - /// The [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. + /// Returns the public key of the [namespace](https://willowprotocol.org/specs/data-model/index.html#namespace) for which this capability grants access. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#owned_cap_granted_namespace) pub fn granted_namespace(&self) -> &NamespacePublicKey { &self.namespace_key } - /// The [`Area`] for which this capability grants access. + /// Returns [`Area`] for which this capability grants access. /// /// [Definition](`https://willowprotocol.org/specs/meadowcap/index.html#owned_cap_granted_area`) pub fn granted_area(&self) -> Area { @@ -303,14 +303,14 @@ where last_delegation.area().clone() } - /// Return a slice of all [`Delegation`]s made to this capability, with a concrete return type. + /// Returns a slice of all [`Delegation`]s made to this capability, with a concrete return type. pub(crate) fn delegations_( &self, ) -> core::slice::Iter> { self.delegations.iter() } - /// Return a slice of all [`Delegation`]s made to this capability. + /// Returns a slice of all [`Delegation`]s made to this capability. pub fn delegations( &self, ) -> impl ExactSizeIterator> @@ -318,22 +318,22 @@ where self.delegations_() } - /// Return the number of delegations present on this capability. + /// Returns the number of delegations present on this capability. pub fn delegations_len(&self) -> usize { self.delegations.len() } - /// Return the public key of the very first user this capability was issued to. + /// Returns the public key of the very first user this capability was issued to. pub fn progenitor(&self) -> &UserPublicKey { &self.user_key } - /// Return the original signature authorising this namespace capability. + /// Returns the original signature authorising this namespace capability. pub fn initial_authorisation(&self) -> &NamespaceSignature { &self.initial_authorisation } - /// A bytestring to be signed for a new [`Delegation`]. + /// Returns a bytestring to be signed for a new [`Delegation`]. /// /// [Definition](https://willowprotocol.org/specs/meadowcap/index.html#owned_handover) fn handover(