[doc]

src/cache.rs

@@ -14,6 +14,7 @@ use crate::traits::SyncSlave;
 use crate::Calendar;
 
 
+/// A CalDAV source that stores its item in a local file
 #[derive(Debug, PartialEq)]
 pub struct Cache {
     backing_file: PathBuf,
@@ -27,16 +28,17 @@ struct CachedData {
 }
 
 impl Cache {
-    /// Get the cache file
+    /// Get the path to the cache file
     pub fn cache_file() -> PathBuf {
         return PathBuf::from(String::from("~/.config/my-tasks/cache.json"))
     }
 
-    /// Initialize a cache from the content of a backing file (if it exists, otherwise start with the default contents)
+    /// Initialize a cache from the content of a valid backing file if it exists.
+    /// Returns an error otherwise
     pub fn from_file(path: &Path) -> Result<Self, Box<dyn Error>> {
         let data = match std::fs::File::open(path) {
-            Err(_) => {
-                CachedData::default()
+            Err(err) => {
+                return Err(format!("Unable to open file {:?}: {}", path, err).into());
             },
             Ok(file) => serde_json::from_reader(file)?,
         };
@@ -72,9 +74,8 @@ impl Cache {
             return;
         };
     }
-}
 
-impl Cache {
+
     pub fn add_calendar(&mut self, calendar: Calendar) {
         self.data.calendars.push(calendar);
     }

src/client.rs

@@ -61,6 +61,7 @@ static TASKS_BODY: &str = r#"
 "#;
 
 
+/// A CalDAV source that fetches its data from a CalDAV server
 pub struct Client {
     url: Url,
     username: String,

src/provider.rs

@@ -28,17 +28,27 @@ where
     S: CalDavSource,
     L: CalDavSource + SyncSlave,
 {
+    /// Create a provider.
+    ///
+    /// `server` is usually a [`Client`](crate::client::Client), `local` is usually a [`Cache`](crate::cache::Cache).
+    /// However, both can be interchangeable. The only difference is that `server` always wins in case of a sync conflict
     pub fn new(server: S, local: L) -> Self {
         Self { server, local }
     }
 
+    /// Returns the data source described as the `server`
     pub fn server(&self) -> &S { &self.server }
+    /// Returns the data source described as the `local`
     pub fn local(&self)  -> &L { &self.local }
     /// Returns the last time the `local` source has been synced
     pub fn last_sync_timestamp(&self) -> Option<DateTime<Utc>> {
         self.local.get_last_sync()
     }
 
+    /// Performs a synchronisation between `local` and `server`.
+    ///
+    /// This bidirectional sync applies additions/deleteions made on a source to the other source.
+    /// In case of conflicts (the same item has been modified on both ends since the last sync, `server` always wins)
     pub async fn sync(&mut self) -> Result<(), Box<dyn Error>> {
         let last_sync = self.local.get_last_sync();
         let cals_server = self.server.get_calendars_mut().await?;