Merge pull request #41 from earthstar-project/more-docs

More doc fixes + update README

README.md

@@ -1,24 +1,47 @@
 # willow-rs
 
-> Protocols for synchronisable data stores. The best parts? Fine-grained permissions, a keen approach to privacy, destructive edits, and a dainty bandwidth and memory footprint.
+> Protocols for synchronisable data stores. The best parts? Fine-grained
+> permissions, a keen approach to privacy, destructive edits, and a dainty
+> bandwidth and memory footprint.
 
-Eventually, this repo will house Rust implementations of
+_Currently_, this repo provides Rust implementations of:
 
-- The [Willow Data Model](https://willowprotocol.org/specs/data-model/index.html#data_model), a mutable eventually-consistent store with improved deletion,
-- [Willow Sideloading protocol](https://willowprotocol.org/specs/sideloading/index.html#sideloading), eventually consistent data delivered by any means possible,
-- [Meadowcap](https://willowprotocol.org/specs/meadowcap/index.html#meadowcap), a capability system configurable to different social contexts,
-- and [Willow General Purpose Sync Protocol](https://willowprotocol.org/specs/sync/index.html#sync), private and efficient synchronisation of Willow stores,
+- [Meadowcap](https://willowprotocol.org/specs/meadowcap/index.html#meadowcap),
+  a capability system adaptable to local needs,
+- Everything in the
+  [Willow Data Model](https://willowprotocol.org/specs/data-model/index.html#data_model)
+  (parameters, paths, entries, groupings, encodings) _except_ for the
+  all-important
+  [store](https://willowprotocol.org/specs/data-model/index.html#store).
 
-probably implemented in that order.
+_Eventually_, this repo will house Rust implementations of:
 
-We welcome contributions! If you're looking for contribution ideas, please see the repo's issues, milestones, and projects.
+- The aforementioned all-important
+  [store](https://willowprotocol.org/specs/data-model/index.html#store),
+- [Willow Sideloading protocol](https://willowprotocol.org/specs/sideloading/index.html#sideloading),
+  eventually consistent data delivered by any means possible,
+- and
+  [Willow General Purpose Sync Protocol](https://willowprotocol.org/specs/sync/index.html#sync),
+  private and efficient synchronisation of Willow stores.
+
+We welcome contributions! If you're looking for contribution ideas, please see
+the repo's issues, milestones, and projects.
 
 ## See also
 
 - [Willow website](https://willowprotocol.org)
-- [willow-js](https://github.com/earthstar-project/willow-js) - TypeScript implementation of Willow Data Model, Sideloading, and General Purpose Sync protocol.
-- [meadowcap-js](https://github.com/earthstar-project/meadowcap-js) - TypeScript implementation of Meadowcap
+- [willow-js](https://github.com/earthstar-project/willow-js) - TypeScript
+  implementation of Willow Data Model, Sideloading, and General Purpose Sync
+  protocol.
+- [meadowcap-js](https://github.com/earthstar-project/meadowcap-js) - TypeScript
+  implementation of Meadowcap
 
 ---
 
-This project was funded through the [NGI0 Core](https://nlnet.nl/core) Fund, a fund established by [NLnet](https://nlnet.nl/) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu/) programme, under the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en) under grant agreement No [101092990](https://cordis.europa.eu/project/id/101092990).
+This project was funded through the [NGI0 Core](https://nlnet.nl/core) Fund, a
+fund established by [NLnet](https://nlnet.nl/) with financial support from the
+European Commission's [Next Generation Internet](https://ngi.eu/) programme,
+under the aegis of
+[DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
+under grant agreement No
+[101092990](https://cordis.europa.eu/project/id/101092990).

data-model/src/encoding/error.rs

@@ -10,7 +10,7 @@ pub enum DecodeError<ProducerError> {
     Producer(ProducerError),
     /// The bytes produced by the producer cannot be decoded into anything meaningful.
     InvalidInput,
-    /// Tried to use a u64 as a usize when the current target's usize is not big enough.
+    /// Tried to use a u64 as a usize when the current compilation target’s usize is not big enough.
     U64DoesNotFitUsize,
 }
 

data-model/src/encoding/traits.rs

@@ -7,7 +7,7 @@ use ufotofu::local_nb::{BulkConsumer, BulkProducer};
 ///
 /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what)
 pub trait Encodable {
-    /// A function from the set `Self` to the set of bytestrings.
+    /// Encode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     ///
     /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s)
     fn encode<Consumer>(
@@ -22,7 +22,7 @@ pub trait Encodable {
 ///
 /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what)
 pub trait Decodable {
-    /// A function from the set of bytestrings to the set of `T`.
+    /// Decade a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     ///
     /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s)
     fn decode<Producer>(
@@ -36,7 +36,7 @@ pub trait Decodable {
 /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*.
 /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`.
 pub trait RelativeEncodable<R> {
-    /// A function from the set `Self` to the set of bytestrings *encoded relative to `reference`*.
+    /// Encode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     fn relative_encode<Consumer>(
         &self,
         reference: &R,
@@ -49,7 +49,7 @@ pub trait RelativeEncodable<R> {
 /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*.
 /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`.
 pub trait RelativeDecodable<R> {
-    /// A function from the set of bytestrings *encoded relative to `Self`* to the set of `T` in relation to `Self`.
+    /// Decode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     fn relative_decode<Producer>(
         reference: &R,
         producer: &mut Producer,

data-model/src/encoding/traits_sync.rs

@@ -5,7 +5,7 @@ use ufotofu::sync::{BulkConsumer, BulkProducer};
 ///
 /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what)
 pub trait Encodable {
-    /// A function from the set `Self` to the set of bytestrings.
+    /// Encode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     ///
     /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s)
     fn encode<Consumer>(&self, consumer: &mut Consumer) -> Result<(), Consumer::Error>
@@ -17,7 +17,7 @@ pub trait Encodable {
 ///
 /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what)
 pub trait Decodable {
-    /// A function from the set of bytestrings to the set of `T`.
+    /// Decode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     ///
     /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s)
     fn decode<Producer>(producer: &mut Producer) -> Result<Self, DecodeError<Producer::Error>>
@@ -29,7 +29,7 @@ pub trait Decodable {
 /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*.
 /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`.
 pub trait RelativeEncodable<R> {
-    /// A function from the set `Self` to the set of bytestrings *encoded relative to `reference`*.
+    /// Encode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     fn relative_encode<Consumer>(
         &self,
         reference: &R,
@@ -42,7 +42,7 @@ pub trait RelativeEncodable<R> {
 /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*.
 /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`.
 pub trait RelativeDecodable<R> {
-    /// A function from the set of bytestrings *encoded relative to `Self`* to the set of `T` in relation to `Self`.
+    /// Decode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what).
     fn relative_decode<Producer>(
         reference: &R,
         producer: &mut Producer,

data-model/src/entry.rs

@@ -7,7 +7,7 @@ use crate::{
     path::Path,
 };
 
-/// A Timestamp is a 64-bit unsigned integer, that is, a natural number between zero (inclusive) and 2^64 - 1 (exclusive).
+/// A Timestamp is a 64-bit unsigned integer, that is, a natural number between zero (inclusive) and 2^64 (exclusive).
 /// Timestamps are to be interpreted as a time in microseconds since the Unix epoch.
 /// [Definition](https://willowprotocol.org/specs/data-model/index.html#Timestamp).
 pub type Timestamp = u64;

data-model/src/grouping/area.rs

@@ -14,7 +14,7 @@ use super::range::Range;
 pub enum AreaSubspace<S: SubspaceId> {
     /// A value that signals that an [`Area`] includes Entries with arbitrary subspace_ids.
     Any,
-    /// A concrete [`SubspaceId`]
+    /// A concrete [`SubspaceId`].
     Id(S),
 }