improve docs

src/dochandle.rs

@@ -28,6 +28,7 @@ pub struct DocHandle {
     /// or the last time it was access by any of the `with_doc` methods.
     /// Putting it in a mutex to maintain an API
     /// that doesn't require a mutabale reference to the handle.
+    /// Note: the mutex is not shared between clones of the same handle.
     last_heads: Mutex<Vec<ChangeHash>>,
 }
 

src/repo.rs

@@ -84,6 +84,8 @@ pub(crate) fn new_repo_future_with_resolver<F>() -> (RepoFuture<F>, RepoFutureRe
 
 impl RepoHandle {
     /// Stop the repo running in the background.
+    /// All documents will have been saved when this returns.
+    ///
     /// This call will block the current thread.
     /// In an async context, use a variant of `spawn_blocking`.
     ///