From 6c9d7b4ed4e3cce64f20e09d858b43d77b08208f Mon Sep 17 00:00:00 2001 From: daladim Date: Sat, 3 Apr 2021 16:27:04 +0200 Subject: [PATCH] [minor] Doc fixes --- src/lib.rs | 4 ++++ src/provider.rs | 3 ++- src/traits.rs | 5 +++-- tests/scenarii.rs | 14 +++++++++++--- 4 files changed, 20 insertions(+), 6 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index a7a398e..61ff99e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,6 +7,10 @@ //! These two "data sources" (actual client and local cache) can be used together in a [`Provider`](provider::Provider). \ //! A `Provider` abstracts these two sources by merging them together into one virtual source. \ //! It also handles synchronisation between the local cache and the server. +//! +//! Note that many methods are defined in common traits (see [`crate::traits`]). +//! +//! See example usage in the `examples/` folder pub mod traits; diff --git a/src/provider.rs b/src/provider.rs index ae16088..8f20401 100644 --- a/src/provider.rs +++ b/src/provider.rs @@ -9,7 +9,8 @@ use crate::traits::CompleteCalendar; use crate::item::SyncStatus; use crate::calendar::SupportedComponents; -/// A data source that combines two `CalDavSources` (usually a server and a local cache), which is able to sync both sources. +/// A data source that combines two `CalDavSource`s (usually a server and a local cache), which is able to sync both sources. +/// This can be used for integration tests, where the remote source is mocked by a `Cache`. pub struct Provider where L: CalDavSource, diff --git a/src/traits.rs b/src/traits.rs index 5ba0600..89df9e5 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -10,6 +10,7 @@ use crate::item::VersionTag; use crate::calendar::CalendarId; use crate::calendar::SupportedComponents; +/// This trait must be implemented by data sources (either local caches or remote CalDAV clients) #[async_trait] pub trait CalDavSource { /// Returns the current calendars that this source contains @@ -92,9 +93,9 @@ pub trait CompleteCalendar : BaseCalendar { /// Mark an item for deletion. /// This is required so that the upcoming sync will know it should also also delete this task from the server - /// (and then call [`immediately_delete_item`] once it has been successfully deleted on the server) + /// (and then call [`CompleteCalendar::immediately_delete_item`] once it has been successfully deleted on the server) async fn mark_for_deletion(&mut self, item_id: &ItemId) -> Result<(), Box>; - /// Immediately remove an item. See [`mark_for_deletion`] + /// Immediately remove an item. See [`CompleteCalendar::mark_for_deletion`] async fn immediately_delete_item(&mut self, item_id: &ItemId) -> Result<(), Box>; } diff --git a/tests/scenarii.rs b/tests/scenarii.rs index 3542f0e..77b220f 100644 --- a/tests/scenarii.rs +++ b/tests/scenarii.rs @@ -1,4 +1,11 @@ //! Multiple scenarios that are performed to test sync operations correctly work +//! +//! This module creates test data. +//! To do so, "scenarii" are defined. A scenario contains an inital state before sync, changes made either on the local or remote side, then the expected final state that should be present in both sources after sync. +//! +//! This module builds actual CalDAV sources (actually [`crate::cache::Cache`]s, that can also mock what would be [`crate::client::Client`]s in a real program) and [`crate::provider::Provider]`s that contain this data +//! +//! This module can also check the sources after a sync contain the actual data we expect #![cfg(feature = "integration_tests")] use std::path::PathBuf; @@ -58,7 +65,7 @@ pub struct ItemScenario { after_sync: LocatedState, } -/// Populate sources with the following: +/// Generate the scenarii required for the following test: /// * At the last sync: both sources had A, B, C, D, E, F, G, H, I, J, K, L, M✓, N✓, O✓ at last sync /// * Before the newer sync, this will be the content of the sources: /// * cache: A, B, D', E, F'', G , H✓, I✓, J✓, M, N✓, O, P, @@ -69,8 +76,8 @@ pub struct ItemScenario { /// /// Notes: /// * X': name has been modified since the last sync -/// * F'/F'': name conflict -/// * G✓: task has been marked as completed +/// * X'/X'': name conflict +/// * X✓: task has been marked as completed pub fn basic_scenarii() -> Vec { let mut tasks = Vec::new(); @@ -365,6 +372,7 @@ pub fn basic_scenarii() -> Vec { tasks } +/// Build a `Provider` that contains the data defined in the given scenarii pub async fn populate_test_provider(scenarii: &[ItemScenario]) -> Provider { let mut remote = Cache::new(&PathBuf::from(String::from("test_cache_remote/"))); let mut local = Cache::new(&PathBuf::from(String::from("test_cache_local/")));