Add addvalue() function documentation.

1 files changed, 17 insertions, 0 deletions

diff --git a/c_src/permdb.c b/c_src/permdb.c
index d3b7394..87edb6d 100644
--- a/c_src/permdb.c
+++ b/c_src/permdb.c
@@ -843,6 +843,23 @@ writedata(permdb_object *state, const unsigned char *key,
 }
 
 
+/*
+ * Adds a key-value pair KEY + DATA by
+ * 1) updating the data file buffer with key and data,
+ * 2) if necessary, adding a new node to the index tree,
+ * 3) marking the parent nodes as dirty and
+ * 4) adding new and changed nodes to the dirtynodes tree.
+ *
+ * If DATA is NULL, the data file buffer is not updated (step 1 above)
+ * and DATAOFFSET is used instead.
+ *
+ * If a duplicate key is detected, nothing is written and 0 is
+ * returned regardless of the data.
+ *
+ * Returns 0 if they key already exists,
+ *         1 if the data was written,
+ *        -1 on error.
+*/
 int
 addvalue(permdb_object *state, const unsigned char *key, unsigned int keylength,
          const unsigned char *data, size_t datalength, node_offset dataoffset)