From 56b86adf02910e9883afed0ceffed2144a531488 Mon Sep 17 00:00:00 2001 From: daladim Date: Mon, 15 Nov 2021 22:32:44 +0100 Subject: [PATCH] [doc] --- Cargo.toml | 2 +- README.md | 5 ++++- examples/provider-sync.rs | 9 ++++++++- src/cache.rs | 2 ++ src/item.rs | 2 +- src/lib.rs | 9 +++++---- src/traits.rs | 12 ++++++++++-- tests/sync-reminder.rs | 1 + 8 files changed, 32 insertions(+), 10 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 1fa947a..1f720b9 100644 --- a/Cargo.toml +++ b/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 diff --git a/README.md b/README.md index 57a57f4..52094f6 100644 --- a/README.md +++ b/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). diff --git a/examples/provider-sync.rs b/examples/provider-sync.rs index 09c803d..8bbe9d0 100644 --- a/examples/provider-sync.rs +++ b/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); diff --git a/src/cache.rs b/src/cache.rs index 639cd64..bc12968 100644 --- a/src/cache.rs +++ b/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>>, Box> { #[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>> { self.data.calendars.get(id).map(|arc| arc.clone()) } diff --git a/src/item.rs b/src/item.rs index c2aaa53..9c45056 100644 --- a/src/item.rs +++ b/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(); diff --git a/src/lib.rs b/src/lib.rs index 87af5dd..1a02dfc 100644 --- a/src/lib.rs +++ b/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 `. \ //! 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. diff --git a/src/traits.rs b/src/traits.rs index bd9adf1..5dc1bd4 100644 --- a/src/traits.rs +++ b/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 { /// Returns the current calendars that this source contains @@ -29,6 +33,8 @@ pub trait CalDavSource { } /// 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, Box>; /// 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, Box>; /// Returns a particular item diff --git a/tests/sync-reminder.rs b/tests/sync-reminder.rs index 463c29a..b98c27c 100644 --- a/tests/sync-reminder.rs +++ b/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 }