Common Update: Better Doxygen Style

df_datalink_sp/src/util/clist.c

@@ -1,3 +1,25 @@
+/*****************************************************************************/
+/**
+ * @file clist.c
+ * @author FanHao ([email protected])
+ * @brief A basic list data structure
+ * @version 0.1
+ * @date 2023-02-23
+ * @note Forked from https://github.com/clibs/list
+ * @copyright Copyright(c) 2024 Beijing Institute of Technology.\n
+ * Lab of Communication and Network
+ *
+ ******************************************************************************/
+
+/**
+ * @addtogroup Utility
+ * @{
+ */
+
+/**
+ * @addtogroup cList
+ * @{
+ */
 #ifndef LIST_MALLOC
 #define LIST_MALLOC malloc
 #endif
@@ -6,19 +28,12 @@
 #define LIST_FREE free
 #endif
 
-//
-// list.c
-//
-// Copyright (c) 2010 TJ Holowaychuk <[email protected]>
-//
-
 #include <stdint.h>
 #include "clist.h"
 
-/*
- * Allocates a new clist_node_t. NULL on failure.
+/**
+ * @brief a new clist_node_t. NULL on failure.
  */
-
 clist_node_t *
 clist_node_new(void *val)
 {
@@ -31,10 +46,9 @@ clist_node_new(void *val)
   return self;
 }
 
-/*
- * Allocate a new clist_t. NULL on failure.
+/**
+ * @brief Allocate a new clist_t. NULL on failure.
  */
-
 clist_t *
 clist_new(void)
 {
@@ -49,11 +63,10 @@ clist_new(void)
   return self;
 }
 
-/*
- * Remove all the node in list.
- * @self: Pointer to the list
+/**
+ * @brief Remove all the node in list.
+ * @param self: Pointer to the list
  */
-
 void clist_clear(clist_t *self)
 {
   clist_node_t *next;
@@ -71,24 +84,21 @@ void clist_clear(clist_t *self)
   self->head = NULL;
 }
 
-/*
- * Free the list.
- * @self: Pointer to the list
+/**
+ * @brief Free the list.
+ * @param self: Pointer to the list
  */
-
 void clist_destroy(clist_t *self)
 {
   clist_clear(self);
   LIST_FREE(self);
 }
 
-/*
- * Append the given node to the list
- * and return the node, NULL on failure.
- * @self: Pointer to the list for popping node
- * @node: the node to push
+/**
+ * @brief Append the given node to the list and return the node, NULL on failure.
+ * @param self: Pointer to the list for popping node
+ * @param node: the node to push
  */
-
 clist_node_t *
 clist_rpush(clist_t *self, clist_node_t *node)
 {
@@ -112,9 +122,9 @@ clist_rpush(clist_t *self, clist_node_t *node)
   return node;
 }
 
-/*
- * Return / detach the last node in the list, or NULL.
- * @self: Pointer to the list for popping node
+/**
+ * @brief Return / detach the last node in the list, or NULL.
+ * @param self: Pointer to the list for popping node
  */
 
 clist_node_t *
@@ -138,9 +148,9 @@ clist_rpop(clist_t *self)
   return node;
 }
 
-/*
- * Return / detach the first node in the list, or NULL.
- * @self: Pointer to the list for popping node
+/**
+ * @brief Return / detach the first node in the list, or NULL.
+ * @param self: Pointer to the list for popping node
  */
 
 clist_node_t *
@@ -164,11 +174,10 @@ clist_lpop(clist_t *self)
   return node;
 }
 
-/*
- * Prepend the given node to the list
- * and return the node, NULL on failure.
- * @self: Pointer to the list for pushing node
- * @node: the node to push
+/**
+ * @brief Prepend the given node to the list and return the node, NULL on failure.
+ * @param self: Pointer to the list for pushing node
+ * @param node: the node to push
  */
 
 clist_node_t *
@@ -194,10 +203,10 @@ clist_lpush(clist_t *self, clist_node_t *node)
   return node;
 }
 
-/*
- * Return the node associated to val or NULL.
- * @self: Pointer to the list for finding given value
- * @val: Value to find
+/**
+ * @brief Return the node associated to val or NULL.
+ * @param self: Pointer to the list for finding given value
+ * @param val: Value to find
  */
 
 clist_node_t *
@@ -230,10 +239,10 @@ clist_find(clist_t *self, void *val)
   return NULL;
 }
 
-/*
- * Return the node at the given index or NULL.
- * @self: Pointer to the list for finding given index
- * @index: the index of node in the list
+/**
+ * @brief Return the node at the given index or NULL.
+ * @param self: Pointer to the list for finding given index
+ * @param index: the index of node in the list
  */
 
 clist_node_t *
@@ -260,10 +269,10 @@ clist_at(clist_t *self, int index)
   return NULL;
 }
 
-/*
- * Remove the given node from the list, freeing it and it's value.
- * @self: Pointer to the list to delete a node
- * @node: Pointer the node to be deleted
+/**
+ * @brief Remove the given node from the list, freeing it and it's value.
+ * @param self: Pointer to the list to delete a node
+ * @param node: Pointer the node to be deleted
  */
 
 void clist_remove(clist_t *self, clist_node_t *node)
@@ -283,8 +292,8 @@ void clist_remove(clist_t *self, clist_node_t *node)
   --self->len;
 }
 
-/*
- * Allocate a new clist_iterator_t. NULL on failure.
+/**
+ * @brief Allocate a new clist_iterator_t. NULL on failure.\n
  * Accepts a direction, which may be LIST_HEAD or LIST_TAIL.
  */
 
@@ -297,8 +306,8 @@ clist_iterator_new(clist_t *list, clist_direction_t direction)
   return clist_iterator_new_from_node(node, direction);
 }
 
-/*
- * Allocate a new clist_iterator_t with the given start
+/**
+ * @brief Allocate a new clist_iterator_t with the given start
  * node. NULL on failure.
  */
 
@@ -313,8 +322,8 @@ clist_iterator_new_from_node(clist_node_t *node, clist_direction_t direction)
   return self;
 }
 
-/*
- * Return the next clist_node_t or NULL when no more
+/**
+ * @brief Return the next clist_node_t or NULL when no more
  * nodes remain in the list.
  */
 
@@ -331,8 +340,8 @@ clist_iterator_next(clist_iterator_t *self)
   return curr;
 }
 
-/*
- * Free the list iterator.
+/**
+ * @brief Free the list iterator.
  */
 
 void clist_iterator_destroy(clist_iterator_t *self)
@@ -340,3 +349,5 @@ void clist_iterator_destroy(clist_iterator_t *self)
   LIST_FREE(self);
   self = NULL;
 }
+/** @} cList*/
+/** @} Utility*/