docs after trees

2 files changed, 11 insertions, 9 deletions

diff --git a/src/simtest/relay.rs b/src/simtest/relay.rs
index da1ce0a..0b7c739 100644
--- a/src/simtest/relay.rs
+++ b/src/simtest/relay.rs
@@ -15,10 +15,11 @@ const SOON: Duration = Duration::from_secs(30);
 
 /// a on `sim` alone, c on `sim2` alone, b on both; a full mesh at each (every member
 /// it reaches is its neighbour), so a pushes its write to b alone, and b, which only
-/// received it, must announce it to c. With a long keepalive, the regular STATUS (every
-/// third keepalive, 15 s) can't be what brings it: c has it within a second (an
-/// announcement waits 200 ms, then c pulls). Without the announcement, a STATUS that
-/// happens to fall into that second would pass it too, once in about 15 runs.
+/// received it, must pass it on to c: along a's tree at once (b is c's parent), else by
+/// announcement 200 to 400 ms later and a pull. With a long keepalive, the regular
+/// STATUS (every third keepalive, 15 s) can't be what brings it: c has it within a
+/// second. Without either, a STATUS that happens to fall into that second would pass it
+/// too, once in about 15 runs.
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn changes_reach_members_the_writer_cant_reach_at_once() {
     let keepalive = Duration::from_secs(5);
diff --git a/src/swarm/relay.rs b/src/swarm/relay.rs
index f79c601..29da2eb 100644
--- a/src/swarm/relay.rs
+++ b/src/swarm/relay.rs
@@ -1,14 +1,15 @@
-//! Passing changes on in a partial mesh (`swarm::topology`).
+//! Passing changes on (`swarm::topology`): along writers' trees (`swarm::tree`), and by
+//! announcement and pull where they don't reach.
 //!
 //! A node pushes its own changes to its neighbours, but nothing it receives goes any
-//! further by itself. So after applying changes from one neighbour, a node *announces*
+//! further by itself but along a writer's tree. So after applying changes from one
+//! neighbour, a node *announces*
 //! its new heads to its other neighbours with a STATUS (heads, about 100 bytes, not the
 //! changes; no keepalive, and answered only by a neighbour whose heads differ). A
 //! neighbour that sees heads it lacks *pulls*: it enters the
 //! announced heads as the peer's heads in its sync state, Automerge asks for what's
-//! missing (`need`), and the announcer answers with exactly those changes. Each node
-//! receives a change about once; the rest is announcements. Regular keepalives work the
-//! same way, so any gap is noticed within a keepalive interval.
+//! missing (`need`), and the announcer answers with exactly those changes. Regular
+//! keepalives work the same way, so any gap is noticed within a keepalive interval.
 //!
 //! Announcements are coalesced: the first applied change schedules one announcement
 //! round `ANNOUNCE_DELAY` later, and every change applied until then rides along. A