doc: make clear that locks can leak and what that means on acquiring …

…a lock (#1026)

gix-lock/src/acquire.rs

@@ -59,6 +59,12 @@ impl File {
     ///
     /// If `boundary_directory` is given, non-existing directories will be created automatically and removed in the case of
     /// a rollback. Otherwise the containing directory is expected to exist, even though the resource doesn't have to.
+    ///
+    /// ### Warning of potential resource leak
+    ///
+    /// Please note that the underlying file will remain if destructors don't run, as is the case when interrupting the application.
+    /// This results in the resource being locked permanently unless the lock file is removed by other means.
+    /// See [the crate documentation](crate) for more information.
     pub fn acquire_to_update_resource(
         at_path: impl AsRef<Path>,
         mode: Fail,
@@ -80,6 +86,12 @@ impl Marker {
     ///
     /// If `boundary_directory` is given, non-existing directories will be created automatically and removed in the case of
     /// a rollback.
+    ///
+    /// ### Warning of potential resource leak
+    ///
+    /// Please note that the underlying file will remain if destructors don't run, as is the case when interrupting the application.
+    /// This results in the resource being locked permanently unless the lock file is removed by other means.
+    /// See [the crate documentation](crate) for more information.
     pub fn acquire_to_hold_resource(
         at_path: impl AsRef<Path>,
         mode: Fail,

gix-lock/src/lib.rs

@@ -1,24 +1,25 @@
 //! git-style registered lock files to make altering resources atomic.
 //!
-//! In this model, reads are always atomic and can be performed directly while writes are facilitated by a locking mechanism
-//! implemented here.
+//! In this model, reads are always atomic and can be performed directly while writes are facilitated by the locking mechanism
+//! implemented here. Locks are acquired atomically, then written to, to finally atomically overwrite the actual resource.
 //!
-//! Lock files mostly `gix-tempfile` with its auto-cleanup and the following:
+//! Lock files are wrapped [`gix-tempfile`](gix_tempfile)-handles and add the following:
 //!
 //! * consistent naming of lock files
 //! * block the thread (with timeout) or fail immediately if a lock cannot be obtained right away
 //! * commit lock files to atomically put them into the location of the originally locked file
 //!
 //! # Limitations
 //!
+//! * [All limitations of `gix-tempfile`](gix_tempfile) apply. **A highlight of such a limitation is resource leakage
+//!   which results in them being permanently locked unless there is user-intervention.**
 //! * As the lock file is separate from the actual resource, locking is merely a convention rather than being enforced.
-//! * The limitations of `gix-tempfile` apply.
 #![deny(missing_docs, rust_2018_idioms, unsafe_code)]
 
+use gix_tempfile::handle::{Closed, Writable};
 use std::path::PathBuf;
 
 pub use gix_tempfile as tempfile;
-use gix_tempfile::handle::{Closed, Writable};
 
 const DOT_LOCK_SUFFIX: &str = ".lock";