From d8c89ec72741467d76086b9f4f23f9d73fc1fd18 Mon Sep 17 00:00:00 2001 From: daladim Date: Wed, 3 Nov 2021 21:55:48 +0100 Subject: [PATCH] [doc] --- src/lib.rs | 3 ++- src/provider/mod.rs | 7 ++++--- src/provider/sync_progress.rs | 3 +++ 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index f710964..d446c4d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,7 +18,8 @@ //! //! ## Examples //! -//! See example usage in the `examples/` folder, that you can run using `cargo run --example ` +//! See example usage in the `examples/` folder, that you can run using `cargo run --example `. \ +//! You can also have a look at `tasklist`, a GUI app that uses `kitchen-fridge` under the hood. pub mod traits; diff --git a/src/provider/mod.rs b/src/provider/mod.rs index 2354fd2..6bb9a5e 100644 --- a/src/provider/mod.rs +++ b/src/provider/mod.rs @@ -68,10 +68,11 @@ where /// Performs a synchronisation between `local` and `remote`, and provide feeedback to the user about the progress. /// /// This bidirectional sync applies additions/deletions made on a source to the other source. - /// In case of conflicts (the same item has been modified on both ends since the last sync, `remote` always wins) + /// In case of conflicts (the same item has been modified on both ends since the last sync, `remote` always wins). /// /// It returns whether the sync was totally successful (details about errors are logged using the `log::*` macros). - /// In case errors happened, the sync might have been partially executed, and you can safely run this function again, since it has been designed to gracefully recover from errors. + /// In case errors happened, the sync might have been partially executed but your data will never be correupted (either locally nor in the server). + /// Simply run this function again, it will re-start a sync, picking up where it failed. pub async fn sync_with_feedback(&mut self, feedback_sender: FeedbackSender) -> bool { let mut progress = SyncProgress::new_with_feedback_channel(feedback_sender); self.run_sync(&mut progress).await @@ -79,7 +80,7 @@ where /// Performs a synchronisation between `local` and `remote`, without giving any feedback. /// - /// See [sync_with_feedback] + /// See [`Self::sync_with_feedback`] pub async fn sync(&mut self) -> bool { let mut progress = SyncProgress::new(); self.run_sync(&mut progress).await diff --git a/src/provider/sync_progress.rs b/src/provider/sync_progress.rs index d2a24bf..7e454fa 100644 --- a/src/provider/sync_progress.rs +++ b/src/provider/sync_progress.rs @@ -36,9 +36,12 @@ impl Default for SyncEvent { +/// See [`feedback_channel`] pub type FeedbackSender = tokio::sync::watch::Sender; +/// See [`feedback_channel`] pub type FeedbackReceiver = tokio::sync::watch::Receiver; +/// Create a feeback channel, that can be used to retrieve the current progress of a sync operation pub fn feedback_channel() -> (FeedbackSender, FeedbackReceiver) { tokio::sync::watch::channel(SyncEvent::default()) }