Merge pull request #52 from earthstar-project/docs-rewrite

Change from imperative to third-person for docs

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<MCL, MCC, MPL> {
         &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<MCL, MCC, MPL, N, S, PD>,
@@ -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<MCL, MCC, MPL, N, S, PD>, 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<MCL, MCC, MPL, N, S, PD>, AT) {
         (self.0, self.1)
     }
 
-    /// Get a reference to the [`Entry`].
+    /// Gets a reference to the [`Entry`].
     pub fn entry(&self) -> &Entry<MCL, MCC, MPL, N, S, PD> {
         &self.0
     }
 
-    /// Get a reference to the [`AuthorisationToken`].
+    /// Gets a reference to the [`AuthorisationToken`].
     pub fn token(&self) -> &AT {
         &self.1
     }

data-model/src/grouping/area.rs

@@ -19,15 +19,15 @@ pub enum AreaSubspace<S: SubspaceId> {
 }
 
 impl<S: SubspaceId> AreaSubspace<S> {
-    /// 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,
             AreaSubspace::Id(id) => sub == id,
         }
     }
 
-    /// Return the intersection between two [`AreaSubspace`].
+    /// Returns the intersection between two [`AreaSubspace`].
     fn intersection(&self, other: &Self) -> Option<Self> {
         match (self, other) {
             (Self::Any, Self::Any) => Some(Self::Any),
@@ -38,7 +38,7 @@ impl<S: SubspaceId> AreaSubspace<S> {
         }
     }
 
-    /// 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<const MCL: usize, const MCC: usize, const MPL: usize, S: Subspac
 }
 
 impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<MCL, MCC, MPL, S> {
-    /// Create a new [`Area`].
+    /// Creates a new [`Area`].
     pub fn new(
         subspace: AreaSubspace<S>,
         path: Path<MCL, MCC, MPL>,
@@ -88,28 +88,29 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<M
         }
     }
 
-    /// Return a reference to the [`AreaSubspace`].
+    /// Returns a reference to the [`AreaSubspace`].
     ///
     /// To be included in this [`Area`], an [`Entry`]’s `subspace_id` must be equal to the subspace_id, unless it is any.
     pub fn subspace(&self) -> &AreaSubspace<S> {
         &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<MCL, MCC, MPL> {
         &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<Timestamp> {
         &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<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<M
         }
     }
 
-    /// Return an [`Area`] which includes all entries within a [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace).
+    /// Returns an [`Area`] which includes all entries within a [subspace](https://willowprotocol.org/specs/data-model/index.html#subspace).
+    ///
     /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#subspace_area).
     pub fn new_subspace(sub: S) -> Self {
         Self {
@@ -129,7 +131,7 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<M
         }
     }
 
-    /// Return whether an [`Area`] [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) an [`Entry`].
+    /// Returns whether an [`Area`] [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include) an [`Entry`].
     pub fn includes_entry<N: NamespaceId, PD: PayloadDigest>(
         &self,
         entry: &Entry<MCL, MCC, MPL, N, S, PD>,
@@ -139,7 +141,7 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<M
             && self.times.includes(&entry.timestamp())
     }
 
-    /// Return whether an [`Area`] fully [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) another [`Area`].
+    /// Returns whether an [`Area`] fully [includes](https://willowprotocol.org/specs/grouping-entries/index.html#area_include_area) another [`Area`].
     pub fn includes_area(&self, area: &Self) -> bool {
         match (&self.subspace, &area.subspace) {
             (AreaSubspace::Any, AreaSubspace::Any) => {
@@ -157,7 +159,8 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId> Area<M
         }
     }
 
-    /// Return the intersection of this [`Area`] with another.
+    /// Returns the intersection of this [`Area`] with another.
+    ///
     /// [Definition](https://willowprotocol.org/specs/grouping-entries/index.html#area_intersection).
     pub fn intersection(&self, other: &Area<MCL, MCC, MPL, S>) -> Option<Self> {
         let subspace_id = self.subspace.intersection(&other.subspace)?;

data-model/src/grouping/area_of_interest.rs

@@ -25,7 +25,8 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId>
         }
     }
 
-    /// 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,

data-model/src/grouping/range.rs

@@ -152,20 +152,20 @@ impl<T> Range<T>
 where
     T: Ord + Clone,
 {
-    /// Construct a range.
+    /// Returns a new [`Range`].
     pub fn new(start: T, end: RangeEnd<T>) -> 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,
             end: RangeEnd::Open,
         }
     }
 
-    /// 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<Self> {
         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<Self> {
         let start = cmp::max(&self.start, &other.start);
         let end = match (&self.end, &other.end) {
@@ -210,7 +210,7 @@ impl<T: Default> Range<T>
 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())
     }

data-model/src/grouping/range_3d.rs

@@ -26,7 +26,7 @@ pub struct Range3d<const MCL: usize, const MCC: usize, const MPL: usize, S: Subs
 impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId>
     Range3d<MCL, MCC, MPL, S>
 {
-    /// Create a new [`Range3d`].
+    /// Creates a new [`Range3d`].
     pub fn new(
         subspaces: Range<S>,
         paths: Range<Path<MCL, MCC, MPL>>,
@@ -39,7 +39,7 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId>
         }
     }
 
-    /// 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<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId>
         )
     }
 
-    /// 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<S> {
         &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<Path<MCL, MCC, MPL>> {
         &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<Timestamp> {
         &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<N: NamespaceId, PD: PayloadDigest>(
         &self,
         entry: &Entry<MCL, MCC, MPL, N, S, PD>,
@@ -76,7 +79,7 @@ impl<const MCL: usize, const MCC: usize, const MPL: usize, S: SubspaceId>
             && 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<MCL, MCC, MPL, S>) -> Option<Self> {
         let paths = self.paths.intersection(&other.paths)?;
         let times = self.times.intersection(&other.times)?;

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<MCL, MCC, MPL, N, S, PD>, available: u64) -> Self {
         Self { entry, available }
     }
 
-    /// The entry in question.
+    /// Returns the entry in question.
     pub fn entry(&self) -> &Entry<MCL, MCC, MPL, N, S, PD> {
         &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<MCL, MCC, MPL, N, S, PD> {
         self.entry
     }
@@ -86,22 +86,22 @@ where
     PD: PayloadDigest,
     AT: AuthorisationToken<MCL, MCC, MPL, N, S, PD>,
 {
-    /// 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<MCL, MCC, MPL, N, S, PD, AT>, available: u64) -> Self {
         Self { entry, available }
     }
 
-    /// The entry in question.
+    /// Returns the authorised entry in question.
     pub fn entry(&self) -> &AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT> {
         &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<MCL, MCC, MPL, N, S, PD, AT> {
         self.entry
     }

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<Self>;
 }
@@ -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<MCL, MCC, MPL, N, S, PD>) -> bool;
 }