[minor] Doc fixes

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;
 

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<L, T, R, U>
 where
     L: CalDavSource<T>,

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<T: BaseCalendar> {
     /// 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<dyn Error>>;
 
-    /// 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<dyn Error>>;
 }

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
+/// * X'/X'': name conflict
-/// * G✓: task has been marked as completed
+/// * X✓: task has been marked as completed
 pub fn basic_scenarii() -> Vec<ItemScenario> {
     let mut tasks = Vec::new();
 
@@ -365,6 +372,7 @@ pub fn basic_scenarii() -> Vec<ItemScenario> {
     tasks
 }
 
+/// Build a `Provider` that contains the data defined in the given scenarii
 pub async fn populate_test_provider(scenarii: &[ItemScenario]) -> Provider<Cache, CachedCalendar, Cache, CachedCalendar> {
     let mut remote = Cache::new(&PathBuf::from(String::from("test_cache_remote/")));
     let mut local = Cache::new(&PathBuf::from(String::from("test_cache_local/")));