From f0392044c2fb4770480273a431045a7404ca1edb Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Thu, 15 Dec 2022 02:48:42 +0000
Subject: [PATCH] Document DbDelete()

---
 man/man3/Db.3 | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/man/man3/Db.3 b/man/man3/Db.3
index 3a8859c..06daca1 100644
--- a/man/man3/Db.3
+++ b/man/man3/Db.3
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: November 26 2022 $
+.Dd $Mdocdate: December 15 2022 $
 .Dt DB 3
 .Os Telodendria Project
 .Sh NAME
@@ -12,6 +12,8 @@
 .Fn DbClose "Db *"
 .Ft DbRef *
 .Fn DbCreate "Db *" "size_t" "..."
+.Ft int
+.Fn DbDelete "Db *" "size_t" "..."
 .Ft DbRef *
 .Fn DbLock "Db *" "size_t" "..."
 .Ft int
@@ -58,6 +60,10 @@ converts a database reference into JSON. At this time, the database actually
 stores objects as JSON, so this just returns an internal pointer, but in the
 future it may have to be generated by decompressing a binary blob, or something
 of that nature.
+.Pp
+.Fn DbDelete
+completely removes an object from the database. It purges it from both the
+cache and the disk as soon as no more references to it are open.
 .Sh RETURN VALUES
 .Pp
 .Fn DbOpen
@@ -74,6 +80,12 @@ to the specified object.
 returns a boolean value indicating whether or not the reference was successfully
 unlocked. If the unlock is successful, then a non-zero value is returned. If it
 isn't, 0 is returned, and it is up to the caller to decide how to proceed.
+.Pp
+.Fn DbDelete
+follows the same return value conventions as
+.Fn DbUnlock ;
+it reports the status of the deletion operation as a boolean value.
+.Pp
 .Fn DbJson
 returns a JSON object. Consult
 .Xr Json 3