Document some sync api

automerge/src/sync.rs

@@ -236,11 +236,16 @@ impl Automerge {
     }
 }
 
+/// The sync message to be sent.
 #[derive(Debug, Clone)]
 pub struct Message {
+    /// The heads of the sender.
     pub heads: Vec<ChangeHash>,
+    /// The hashes of any changes that are being explicitly requested from the recipient.
     pub need: Vec<ChangeHash>,
+    /// A summary of the changes that the sender already has.
     pub have: Vec<Have>,
+    /// The changes for the recipient to apply.
     pub changes: Vec<Change>,
 }
 

automerge/src/sync/state.rs

@@ -5,6 +5,7 @@ use crate::{decoding, decoding::Decoder, ChangeHash};
 
 const SYNC_STATE_TYPE: u8 = 0x43; // first byte of an encoded sync state, for identification
 
+/// The state of synchronisation with a peer.
 #[derive(Debug, Clone, Default)]
 pub struct State {
     pub shared_heads: Vec<ChangeHash>,
@@ -15,9 +16,15 @@ pub struct State {
     pub sent_hashes: HashSet<ChangeHash>,
 }
 
+/// A summary of the changes that the sender of the message already has.
+/// This is implicitly a request to the recipient to send all changes that the
+/// sender does not already have.
 #[derive(Debug, Clone, Default)]
 pub struct Have {
+    /// The heads at the time of the last successful sync with this recipient.
     pub last_sync: Vec<ChangeHash>,
+    /// A bloom filter summarising all of the changes that the sender of the message has added
+    /// since the last sync.
     pub bloom: BloomFilter,
 }