[PATCH v7 20/38] api-lockfile: document edge cases

[Michael Haggerty <mhagger@alum.mit.edu>]

* Document the behavior of commit_lock_file() when it fails, namely
  that it rolls back the lock_file object and sets errno
  appropriately.

* Document the behavior of rollback_lock_file() when called for a
  lock_file object that has already been committed or rolled back,
  namely that it is a NOOP.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
---
 Documentation/technical/api-lockfile.txt | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
index d3bf940..9805da0 100644
--- a/Documentation/technical/api-lockfile.txt
+++ b/Documentation/technical/api-lockfile.txt
@@ -100,6 +100,10 @@ unable_to_lock_die::
 
 	Emit an appropriate error message and `die()`.
 
+Similarly, `commit_lock_file` and `close_lock_file` return 0 on
+success. On failure they set `errno` appropriately, do their best to
+roll back the lockfile, and return -1.
+
 
 Flags
 -----
@@ -144,18 +148,22 @@ commit_lock_file::
 
 	Take a pointer to the `struct lock_file` initialized with an
 	earlier call to `hold_lock_file_for_update` or
-	`hold_lock_file_for_append`, close the file descriptor and
+	`hold_lock_file_for_append`, close the file descriptor, and
 	rename the lockfile to its final destination. Return 0 upon
-	success or a negative value on failure to `close(2)` or
-	`rename(2)`. It is a bug to call `commit_lock_file()` for a
-	`lock_file` object that is not currently locked.
+	success. On failure, roll back the lock file and return -1,
+	with `errno` set to the value from the failing call to
+	`close(2)` or `rename(2)`. It is a bug to call
+	`commit_lock_file` for a `lock_file` object that is not
+	currently locked.
 
 rollback_lock_file::
 
 	Take a pointer to the `struct lock_file` initialized with an
 	earlier call to `hold_lock_file_for_update` or
 	`hold_lock_file_for_append`, close the file descriptor and
-	remove the lockfile.
+	remove the lockfile. It is a NOOP to call
+	`rollback_lock_file()` for a `lock_file` object that has
+	already been committed or rolled back.
 
 close_lock_file::
 
@@ -163,7 +171,7 @@ close_lock_file::
 	earlier call to `hold_lock_file_for_update` or
 	`hold_lock_file_for_append`, and close the file descriptor.
 	Return 0 upon success. On failure to `close(2)`, return a
-	negative value and rollback the lock file. Usually
+	negative value and roll back the lock file. Usually
 	`commit_lock_file` or `rollback_lock_file` should eventually
 	be called if `close_lock_file` succeeds.
 
-- 
2.1.0