[doc]

Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 description = "A CalDAV (ical file management over WebDAV) library"
 repository = "https://github.com/daladim/kitchen-fridge"
 license = "MIT"
-keywords = ["CalDAV", "client", "WebDAV", "todo", "RFC4791"]
+keywords = ["CalDAV", "client", "WebDAV", "todo", "iCloud"]
 categories = ["network-programming", "web-programming::http-client"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

README.md

@@ -1,5 +1,8 @@
 # kitchen-fridge
 
-kitchen-fridge is a CalDAV (iCal file transfer over WebDAV) Rust library.
+kitchen-fridge is a CalDAV (iCal file transfer over WebDAV) Rust client library.
 
 Its [documentation](https://docs.rs/kitchen-fridge/) is available on docs.rs.
+
+
+CalDAV is described as "Calendaring Extensions to WebDAV" in [RFC 4791](https://datatracker.ietf.org/doc/html/rfc4791) and [RFC 7986](https://datatracker.ietf.org/doc/html/rfc7986) and the underlying iCal format is described at least in [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545).

examples/provider-sync.rs

@@ -35,8 +35,15 @@ async fn main() {
     env_logger::init();
 
     println!("This examples show how to sync a remote server with a local cache, using a Provider.");
-    println!("Make sure you have edited your settings.rs to include correct URLs and credentials.");
+    println!("Make sure you have edited the constants in this file to include correct URLs and credentials.");
     println!("You can also set the RUST_LOG environment variable to display more info about the sync.");
+    println!("");
+    println!("This will use the following settings:");
+    println!("  * URL = {}", URL);
+    println!("  * USERNAME = {}", USERNAME);
+    println!("  * EXAMPLE_TASK_URL = {}", EXAMPLE_TASK_URL);
+    println!("  * EXAMPLE_EXISTING_CALENDAR_URL = {}", EXAMPLE_EXISTING_CALENDAR_URL);
+    println!("  * EXAMPLE_CREATED_CALENDAR_URL = {}", EXAMPLE_CREATED_CALENDAR_URL);
     pause();
 
     let cache_path = Path::new(CACHE_FOLDER);

src/cache.rs

@@ -184,6 +184,7 @@ impl Drop for Cache {
 }
 
 impl Cache {
+    /// The non-async version of [`crate::traits::CalDavSource::get_calendars`]
     pub fn get_calendars_sync(&self) -> Result<HashMap<CalendarId, Arc<Mutex<CachedCalendar>>>, Box<dyn Error>> {
         #[cfg(feature = "local_calendar_mocks_remote_calendars")]
         self.mock_behaviour.as_ref().map_or(Ok(()), |b| b.lock().unwrap().can_get_calendars())?;
@@ -194,6 +195,7 @@ impl Cache {
         )
     }
 
+    /// The non-async version of [`crate::traits::CalDavSource::get_calendar`]
     pub fn get_calendar_sync(&self, id: &CalendarId) -> Option<Arc<Mutex<CachedCalendar>>> {
         self.data.calendars.get(id).map(|arc| arc.clone())
     }

src/item.rs

@@ -175,7 +175,7 @@ impl VersionTag {
         &self.tag
     }
 
-    /// Generate a random VesionTag
+    /// Generate a random VersionTag
     #[cfg(feature = "local_calendar_mocks_remote_calendars")]
     pub fn random() -> Self {
         let random = uuid::Uuid::new_v4().to_hyphenated().to_string();

src/lib.rs

@@ -1,6 +1,7 @@
-//! This crate provides a way to manage CalDAV data.
+//! This crate provides a CalDAV client.
+//! CalDAV is described as "Calendaring Extensions to WebDAV" in [RFC 4791](https://datatracker.ietf.org/doc/html/rfc4791) and [RFC 7986](https://datatracker.ietf.org/doc/html/rfc7986) and the underlying iCal format is described at least in [RFC 5545](https://datatracker.ietf.org/doc/html/rfc5545).
 //!
-//! Its initial implementation only supported TODO events, so that it could fetch and update a CalDAV-hosted todo-list...just like [sticky notes on a kitchen fridge](https://www.google.com/search?q=kitchen+fridge+todo+list&tbm=isch) would. \
+//! This initial implementation only supports TODO events. This it can fetch and update a CalDAV-hosted todo-list...just like [sticky notes on a kitchen fridge](https://www.google.com/search?q=kitchen+fridge+todo+list&tbm=isch) would. \
 //! Supporting other items (and especially regular CalDAV calendar events) should be fairly trivial, as it should boil down to adding little logic in iCal files parsing, but any help is appreciated :-)
 //!
 //! ## Possible uses
@@ -12,7 +13,7 @@
 //!
 //! These two "data sources" (actual client and local cache) can be used together in a [`CalDavProvider`](CalDavProvider). \
 //! A `CalDavProvider` abstracts these two sources by merging them together into one virtual source. \
-//! It also handles synchronisation between the local cache and the server.
+//! It also handles synchronisation between the local cache and the server, and robustly recovers from any network error (so that it never corrupts the local or remote source).
 //!
 //! Note that many methods are defined in common traits (see [`crate::traits`]).
 //!
@@ -21,7 +22,7 @@
 //! See example usage in the `examples/` folder, that you can run using `cargo run --example <example-name>`. \
 //! You can also have a look at `tasklist`, a GUI app that uses `kitchen-fridge` under the hood.
 //!
-//! # Compile-time configuration options
+//! ## Compile-time configuration options
 //!
 //! Have a look at the [`config`] module to see what options can be overridden at compile-time.
 

src/traits.rs

@@ -1,3 +1,5 @@
+//! Traits used by multiple structs in this crate
+
 use std::error::Error;
 use std::collections::{HashMap, HashSet};
 use std::sync::{Arc, Mutex};
@@ -14,6 +16,8 @@ use crate::calendar::SupportedComponents;
 use crate::resource::Resource;
 
 /// This trait must be implemented by data sources (either local caches or remote CalDAV clients)
+///
+/// Note that some concrete types (e.g. [`crate::cache::Cache`]) can also provide non-async versions of these functions
 #[async_trait]
 pub trait CalDavSource<T: BaseCalendar> {
     /// Returns the current calendars that this source contains
@@ -29,6 +33,8 @@ pub trait CalDavSource<T: BaseCalendar> {
 }
 
 /// This trait contains functions that are common to all calendars
+///
+/// Note that some concrete types (e.g. [`crate::calendar::cached_calendar::CachedCalendar`]) can also provide non-async versions of these functions
 #[async_trait]
 pub trait BaseCalendar {
     /// Returns the calendar name
@@ -65,6 +71,8 @@ pub trait BaseCalendar {
 
 
 /// Functions availabe for calendars that are backed by a CalDAV server
+///
+/// Note that some concrete types (e.g. [`crate::calendar::cached_calendar::CachedCalendar`]) can also provide non-async versions of these functions
 #[async_trait]
 pub trait DavCalendar : BaseCalendar {
     /// Create a new calendar
@@ -95,6 +103,8 @@ pub trait DavCalendar : BaseCalendar {
 /// Functions availabe for calendars we have full knowledge of
 ///
 /// Usually, these are local calendars fully backed by a local folder
+///
+/// Note that some concrete types (e.g. [`crate::calendar::cached_calendar::CachedCalendar`]) can also provide non-async versions of these functions
 #[async_trait]
 pub trait CompleteCalendar : BaseCalendar {
     /// Create a new calendar
@@ -104,8 +114,6 @@ pub trait CompleteCalendar : BaseCalendar {
     async fn get_item_ids(&self) -> Result<HashSet<ItemId>, Box<dyn Error>>;
 
     /// Returns all items that this calendar contains
-    ///
-    /// See [`crate::utils::comparison`] for helper functions that help sorting the results
     async fn get_items(&self) -> Result<HashMap<ItemId, &Item>, Box<dyn Error>>;
 
     /// Returns a particular item

tests/sync-reminder.rs

@@ -3,4 +3,5 @@
 fn do_not_forget_to_run_tests_with_specific_features() {
     // This is just a reminder that there are tests that can be run only when cargo feature "integration_tests" is enabled.
     // See `sync.rs`
+    // See also the CI configuration in the `.gitlab` folder
 }