From e08933b9f160cf794296b673333855da6ea90a9e Mon Sep 17 00:00:00 2001
From: John Sanpe <sanpeqf@gmail.com>
Date: Sun, 12 Jan 2025 11:17:25 +0800
Subject: [PATCH] docs skiplist: added api comments

Signed-off-by: John Sanpe <sanpeqf@gmail.com>
---
 include/bfdev/skiplist.h | 51 +++++++++++++++++++++++++++++++---------
 src/skiplist.c           | 23 ++++++++++--------
 2 files changed, 53 insertions(+), 21 deletions(-)

diff --git a/include/bfdev/skiplist.h b/include/bfdev/skiplist.h
index 0f122275..c5807bd5 100644
--- a/include/bfdev/skiplist.h
+++ b/include/bfdev/skiplist.h
@@ -29,26 +29,55 @@ struct bfdev_skip_head {
     bfdev_list_head_t nodes[0];
 };
 
+/**
+ * bfdev_skiplist_find - find a node in the skiplist.
+ * @head: the skiplist head to find in.
+ * @find: the find function for this skiplist.
+ * @pdata: the private data for @find.
+ */
+extern bfdev_skip_node_t *
+bfdev_skiplist_find(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata);
+
+/**
+ * bfdev_skiplist_insert - insert a node into the skiplist.
+ * @head: the skiplist head to insert into.
+ * @key: the key for this skiplist.
+ * @cmp: the compare function for this skiplist.
+ * @pdata: the private data for @cmp.
+ */
 extern int
-bfdev_skiplist_insert(bfdev_skip_head_t *head, void *key, bfdev_cmp_t cmp,
-                      void *pdata);
+bfdev_skiplist_insert(bfdev_skip_head_t *head, void *key,
+                      bfdev_cmp_t cmp, void *pdata);
 
-extern void
+/**
+ * bfdev_skiplist_delete - delete a node from the skiplist.
+ * @head: the skiplist head to delete from.
+ * @find: the find function for this skiplist.
+ * @pdata: the private data for @find.
+ */
+extern int
 bfdev_skiplist_delete(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata);
 
-extern bfdev_skip_node_t *
-bfdev_skiplist_find(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata);
-
+/**
+ * bfdev_skiplist_reset - reset all nodes in a skiplist.
+ * @head: the skiplist head to reset.
+ * @release: the function to release each node.
+ * @pdata: the private data for @release.
+ */
 extern void
-bfdev_skiplist_reset(bfdev_skip_head_t *head, bfdev_release_t release,
-                     void *pdata);
-
+bfdev_skiplist_reset(bfdev_skip_head_t *head,
+                     bfdev_release_t release, void *pdata);
+/**
+ * bfdev_skiplist_create - create a skiplist header.
+ * @alloc: the allocator for this skiplist.
+ * @levels: the levels for this skiplist.
+ */
 extern bfdev_skip_head_t *
 bfdev_skiplist_create(const bfdev_alloc_t *alloc, unsigned int levels);
 
 extern void
-bfdev_skiplist_destroy(bfdev_skip_head_t *head, bfdev_release_t release,
-                       void *pdata);
+bfdev_skiplist_destroy(bfdev_skip_head_t *head,
+                       bfdev_release_t release, void *pdata);
 
 /**
  * bfdev_skiplist_for_each - iterate over list of given type.
diff --git a/src/skiplist.c b/src/skiplist.c
index 2e38c458..5444f635 100644
--- a/src/skiplist.c
+++ b/src/skiplist.c
@@ -60,6 +60,16 @@ skipnode_find(bfdev_skip_head_t *head, bfdev_find_t find,
     return NULL;
 }
 
+export bfdev_skip_node_t *
+bfdev_skiplist_find(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata)
+{
+    bfdev_skip_node_t *node;
+
+    node = skipnode_find(head, find, pdata, NULL);
+
+    return node;
+}
+
 export int
 bfdev_skiplist_insert(bfdev_skip_head_t *head, void *key, bfdev_cmp_t cmp,
                       void *pdata)
@@ -100,7 +110,7 @@ bfdev_skiplist_insert(bfdev_skip_head_t *head, void *key, bfdev_cmp_t cmp,
     return 0;
 }
 
-export void
+export int
 bfdev_skiplist_delete(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata)
 {
     const bfdev_alloc_t *alloc;
@@ -110,7 +120,7 @@ bfdev_skiplist_delete(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata)
     alloc = head->alloc;
     node = skipnode_find(head, find, pdata, &level);
     if (bfdev_unlikely(!node))
-        return;
+        return -BFDEV_ENOENT;
 
     while (level--) {
         bfdev_list_del(&node->list[level]);
@@ -119,15 +129,8 @@ bfdev_skiplist_delete(bfdev_skip_head_t *head, bfdev_find_t find, void *pdata)
     }
 
     bfdev_free(alloc, node);
-}
 
-export bfdev_skip_node_t *
-bfdev_skiplist_find(bfdev_skip_head_t *head,
-                    bfdev_find_t find, void *pdata)
-{
-    bfdev_skip_node_t *node;
-    node = skipnode_find(head, find, pdata, NULL);
-    return node;
+    return -BFDEV_ENOERR;
 }
 
 static void