Document DbDelete()

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