Add comment/documentation for Store::move_by_id()

libimagstore/src/store.rs

@@ -649,6 +649,41 @@ impl Store {
     }
 
     /// Move an entry without loading
+    ///
+    /// This function moves an entry from one path to another.
+    ///
+    /// Generally, this function shouldn't be used by library authors, if they "just" want to move
+    /// something around. A library for moving entries while caring about meta-data and links.
+    ///
+    /// # Errors
+    ///
+    /// This function returns an error in certain cases:
+    ///
+    /// * If pre-move-hooks error (if they return an error which indicates that the action should be
+    ///   aborted)
+    /// * If the about-to-be-moved entry is borrowed
+    /// * If the lock on the internal data structure cannot be aquired
+    /// * If the new path already exists
+    /// * If the about-to-be-moved entry does not exist
+    /// * If the FS-operation failed
+    /// * If the post-move-hooks error (though the operation has succeeded then).
+    ///
+    /// # Warnings
+    ///
+    /// This should be used with _great_ care, as moving an entry from `a` to `b` might result in
+    /// dangling links (see below).
+    ///
+    /// ## Moving linked entries
+    ///
+    /// If the entry which is moved is linked to another entry, these links get invalid (but we do
+    /// not detect this here). As links are always two-way-links, so `a` is not only linked to `b`,
+    /// but also the other way round, moving `b` to `c` results in the following scenario:
+    ///
+    /// * `a` links to `b`, which does not exist anymore.
+    /// * `c` links to `a`, which does exist.
+    ///
+    /// So the link is _partly dangling_, so to say.
+    ///
     pub fn move_by_id(&self, old_id: StoreId, new_id: StoreId) -> Result<()> {
         let new_id = new_id.with_base(self.path().clone());
         let old_id = old_id.with_base(self.path().clone());