Doc and usability

examples/provider-sync.rs

@@ -4,12 +4,10 @@ use chrono::{Utc};
 
 use kitchen_fridge::{client::Client, traits::CalDavSource};
 use kitchen_fridge::calendar::{CalendarId, SupportedComponents};
-use kitchen_fridge::calendar::cached_calendar::CachedCalendar;
-use kitchen_fridge::calendar::remote_calendar::RemoteCalendar;
 use kitchen_fridge::Item;
 use kitchen_fridge::Task;
 use kitchen_fridge::task::CompletionStatus;
-use kitchen_fridge::ItemId;
+use kitchen_fridge::item::ItemId;
 use kitchen_fridge::cache::Cache;
 use kitchen_fridge::CalDavProvider;
 use kitchen_fridge::traits::BaseCalendar;
@@ -43,7 +41,7 @@ async fn main() {
             Cache::new(&cache_path)
         }
     };
-    let mut provider = Provider::new(client, cache);
+    let mut provider = CalDavProvider::new(client, cache);
 
     let cals = provider.local().get_calendars().await.unwrap();
     println!("---- Local items, before sync -----");
@@ -62,8 +60,7 @@ async fn main() {
     add_items_and_sync_again(&mut provider).await;
 }
 
-async fn add_items_and_sync_again(
+async fn add_items_and_sync_again(provider: &mut CalDavProvider)
-    provider: &mut Provider<Cache, CachedCalendar, Client, RemoteCalendar>)
 {
     println!("\nNow, we'll add a calendar and a few tasks and run the sync again.");
     pause();
@@ -104,7 +101,7 @@ async fn add_items_and_sync_again(
 }
 
 async fn complete_item_and_sync_again(
-    provider: &mut Provider<Cache, CachedCalendar, Client, RemoteCalendar>,
+    provider: &mut CalDavProvider,
     changed_calendar_id: &CalendarId,
     id_to_complete: &ItemId)
 {
@@ -128,7 +125,7 @@ async fn complete_item_and_sync_again(
 }
 
 async fn remove_items_and_sync_again(
-    provider: &mut Provider<Cache, CachedCalendar, Client, RemoteCalendar>,
+    provider: &mut CalDavProvider,
     changed_calendar_id: &CalendarId,
     id_to_remove: &ItemId)
 {

src/calendar/cached_calendar.rs

@@ -4,7 +4,7 @@ use std::error::Error;
 use serde::{Deserialize, Serialize};
 use async_trait::async_trait;
 
-use crate::SyncStatus;
+use crate::item::SyncStatus;
 use crate::traits::{BaseCalendar, CompleteCalendar};
 use crate::calendar::{CalendarId, SupportedComponents};
 use crate::Item;

src/calendar/mod.rs

@@ -1,3 +1,5 @@
+//! Various objects that implement Calendar-related traits
+
 pub mod cached_calendar;
 pub mod remote_calendar;
 

src/client.rs

@@ -50,7 +50,7 @@ static CAL_BODY: &str = r#"
 
 
 
-pub async fn sub_request(resource: &Resource, method: &str, body: String, depth: u32) -> Result<String, Box<dyn Error>> {
+pub(crate) async fn sub_request(resource: &Resource, method: &str, body: String, depth: u32) -> Result<String, Box<dyn Error>> {
     let method = method.parse()
         .expect("invalid method name");
 
@@ -71,7 +71,7 @@ pub async fn sub_request(resource: &Resource, method: &str, body: String, depth:
     Ok(text)
 }
 
-pub async fn sub_request_and_extract_elem(resource: &Resource, body: String, items: &[&str]) -> Result<String, Box<dyn Error>> {
+pub(crate) async fn sub_request_and_extract_elem(resource: &Resource, body: String, items: &[&str]) -> Result<String, Box<dyn Error>> {
     let text = sub_request(resource, "PROPFIND", body, 0).await?;
 
     let mut current_element: &Element = &text.parse()?;
@@ -84,7 +84,7 @@ pub async fn sub_request_and_extract_elem(resource: &Resource, body: String, ite
     Ok(current_element.text())
 }
 
-pub async fn sub_request_and_extract_elems(resource: &Resource, method: &str, body: String, item: &str) -> Result<Vec<Element>, Box<dyn Error>> {
+pub(crate) async fn sub_request_and_extract_elems(resource: &Resource, method: &str, body: String, item: &str) -> Result<Vec<Element>, Box<dyn Error>> {
     let text = sub_request(resource, method, body, 1).await?;
 
     let element: &Element = &text.parse()?;
@@ -96,7 +96,7 @@ pub async fn sub_request_and_extract_elems(resource: &Resource, method: &str, bo
 }
 
 
-/// A CalDAV source that fetches its data from a CalDAV server
+/// A CalDAV data source that fetches its data from a CalDAV server
 pub struct Client {
     resource: Resource,
 

src/event.rs

@@ -1,4 +1,4 @@
-//! Calendar events
+//! Calendar events (iCal `VEVENT` items)
 
 use serde::{Deserialize, Serialize};
 use chrono::{DateTime, Utc};
@@ -6,7 +6,7 @@ use chrono::{DateTime, Utc};
 use crate::item::ItemId;
 use crate::item::SyncStatus;
 
-/// TODO: implement Event one day.
+/// TODO: implement `Event` one day.
 /// This crate currently only supports tasks, not calendar events.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct Event {

src/item.rs

@@ -1,3 +1,4 @@
+//! CalDAV items (todo, events, journals...)
 // TODO: move Event and Task to nest them in crate::items::calendar::Calendar?
 
 use std::fmt::{Display, Formatter};

src/lib.rs

@@ -23,25 +23,24 @@
 pub mod traits;
 
 pub mod calendar;
-mod item;
+pub mod item;
 pub use item::Item;
-pub use item::ItemId;
-pub use item::VersionTag;
-pub use item::SyncStatus;
 pub mod task;
 pub use task::Task;
-mod event;
+pub mod event;
 pub use event::Event;
 pub mod provider;
-pub use provider::Provider;
 pub mod mock_behaviour;
 
 pub mod client;
 pub use client::Client;
 pub mod cache;
-pub use cache::Cache;
 pub mod ical;
 
 pub mod settings;
 pub mod utils;
 pub mod resource;
+
+/// Unless you want another kind of Provider to write integration tests, you'll probably want this kind of Provider. \
+/// See alse the [`Provider` documentation](crate::provider::Provider)
+pub type CalDavProvider = provider::Provider<cache::Cache, calendar::cached_calendar::CachedCalendar, Client, calendar::remote_calendar::RemoteCalendar>;

src/mock_behaviour.rs

@@ -1,4 +1,5 @@
 //! This module provides ways to tweak mocked calendars, so that they can return errors on some tests
+#![cfg(feature = "local_calendar_mocks_remote_calendars")]
 
 use std::error::Error;
 

src/provider.rs

@@ -43,7 +43,7 @@ impl SyncResult {
 
 /// A data source that combines two `CalDavSource`s, which is able to sync both sources.
 ///
-/// Usually, you will only need to use a provider between a server and a local cache, that is to say `Provider<Cache, CachedCalendar, Client, RemoteCalendar>`
+/// Usually, you will only need to use a provider between a server and a local cache, that is to say a [`CalDavProvider`](crate::CalDavProvider), i.e. a `Provider<Cache, CachedCalendar, Client, RemoteCalendar>`. \
 /// However, providers can be used for integration tests, where the remote source is mocked by a `Cache`.
 pub struct Provider<L, T, R, U>
 where
@@ -372,7 +372,7 @@ where
 }
 
 
-pub async fn get_or_insert_counterpart_calendar<H, N, I>(haystack_descr: &str, haystack: &mut H, cal_id: &CalendarId, needle: Arc<Mutex<N>>)
+async fn get_or_insert_counterpart_calendar<H, N, I>(haystack_descr: &str, haystack: &mut H, cal_id: &CalendarId, needle: Arc<Mutex<N>>)
     -> Result<Arc<Mutex<I>>, Box<dyn Error>>
 where
     H: CalDavSource<I>,

src/task.rs

@@ -1,3 +1,5 @@
+//! To-do tasks (iCal `VTODO` item)
+
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;
 use chrono::{DateTime, Utc};

src/traits.rs

@@ -4,7 +4,7 @@ use std::sync::{Arc, Mutex};
 
 use async_trait::async_trait;
 
-use crate::SyncStatus;
+use crate::item::SyncStatus;
 use crate::item::Item;
 use crate::item::ItemId;
 use crate::item::VersionTag;