Common Update: Better Doxygen Style

2024-03-28 00:00:59 +08:00
parent 9b416114a1
commit bab91e13df
43 changed files with 1800 additions and 1195 deletions
@@ -1,34 +1,25 @@
 /*****************************************************************************/
 /**
- * Description: A simple circular FIFO bounded queue
+ * @file circ_queue.c
+ * @author FanHao ([email protected])
+ * @brief A simple circular FIFO bounded queue
+ * @version 0.1
+ * @date 2023-02-23
+ * @note Forked from https://github.com/chrismerck/rpa_queue.git
+ * @copyright Copyright(c) 2024 Beijing Institute of Technology.\n
+ * Lab of Communication and Network
 *
- * Author: Fan Hao
- * Date: 2023-02-23 10:29
- * LastEditors: Fan Hao
- * LastEditTime: 2023-02-23 13:18
- * Revisions: Rev 0.0
- * History:
- * [2023-02-23]: Initial Version.
- *
- * Copyright(c) 2023 Beijing Institute of Technology.
- * Lab of Communication and Networking
- * NOTE: Forked from https://github.com/chrismerck/rpa_queue.git
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements.  See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
 ******************************************************************************/

+/**
+ * @addtogroup Utility
+ * @{
+ */
+
+/**
+ * @addtogroup CircularQueue
+ * @{
+ */
 #include "circ_queue.h"
 #include "common.h"
 #include <stdio.h>
@@ -56,7 +47,7 @@ void CircQueueFree(CIRC_QUEUE *queue)
 }

 /**
- * Initialize the CIRC_QUEUE.
+ * @brief Initialize the CIRC_QUEUE.
 */
 bool CircQueueCreate(CIRC_QUEUE **q, uint32_t queueCapacity)
 {
@@ -87,7 +78,7 @@ error:
 }

 /**
- * Push new data onto the queue.
+ * @brief Push new data onto the queue.
 */
 bool CircQueuePush(CIRC_QUEUE *queue, void *data)
 {
@@ -110,7 +101,7 @@ bool CircQueuePush(CIRC_QUEUE *queue, void *data)
 }

 /**
- * Return current number of element in queue.
+ * @brief Return current number of element in queue.
 */
 inline uint32_t CircQueueSize(CIRC_QUEUE *queue)
 {
@@ -118,7 +109,7 @@ inline uint32_t CircQueueSize(CIRC_QUEUE *queue)
 }

 /**
- * Retrieves the next item from the queue.
+ * @brief Retrieves the next item from the queue.
 */
 bool CircQueuePop(CIRC_QUEUE *queue, void **data)
 {
@@ -139,3 +130,5 @@ bool CircQueuePop(CIRC_QUEUE *queue, void **data)
  }
  return true;
 }
+/** @} CircularQueue*/
+/** @} Utility*/
@@ -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*/
@@ -10,11 +10,14 @@
 * [2022-07-16]: New branch for Dijian.
 * [2021-11-16]: Initial version.
 *
- * Copyright(c) 2021 Beijing Institute of Technology.
+ * Copyright(c) 2024 Beijing Institute of Technology.
 * Lab of Communication and Networking
 *
 ******************************************************************************/
-
+/**
+ * @addtogroup COMMON_MACRO
+ * @{
+ */
 /***************************** Include Files *********************************/
 #include "common.h"
 #include "error.h"
@@ -44,3 +47,5 @@ void AppAssert(const char *file, int line)
 	while (1)
 		;
 }
+
+/** @} */
@@ -11,11 +11,14 @@
 * [2022-07-17]: Add CRC16_0x8005 CRC8_0x31.
 * [2022-01-06]: Initial verion (Basic CRC-16).
 *
- * Copyright(c) 2021 Beijing Institute of Technology.
+ * Copyright(c) 2024 Beijing Institute of Technology.
 * Lab of Communication and Networking
 *
 ******************************************************************************/
-
+/**
+ * @addtogroup Utility
+ * @{
+ */
 #include "util.h"
 #include "error.h"

@@ -437,3 +440,5 @@ bool crc16_check(uint8_t *buffPtr, uint32_t dataLen, uint32_t crcOffset, uint16_
        return false;
    }
 }
+
+/** @}*/
@@ -1,15 +1,30 @@
-/******************************************************************************/
+/*****************************************************************************/
+/**
+ * @file util.c
+ * @author FanHao ([email protected])
+ * @brief Utility functions implementation file
+ * @version 0.0
+ * @date 2023-05-06
+ *
+ * @copyright Copyright(c) 2024 Beijing Institute of Technology.\n
+ * Lab of Communication and Network
+ *
+ ******************************************************************************/
+
 /***************************** Include Files **********************************/
-/******************************************************************************/
+
+/**
+ * @addtogroup Utility
+ * @{
+ */
+
 #include <string.h>
 #include <stdlib.h>
 // #include <arm_acle.h>
 #include "util.h"
 #include "error.h"

-/******************************************************************************/
 /************************** Functions Implementation **************************/
-/******************************************************************************/
 #ifdef __BITSWAP_TABLE
 static uint8_t byte_flipLR[256] =
 {
@@ -48,17 +63,26 @@ static uint8_t byte_flipLR[256] =
 };
 #endif

+/**
+ * @brief Write a 32bit word to specific memory address
+ */
 inline void IO_Out32(uintptr_t addr, uint32_t value)
 {
 	volatile uint32_t *localAddr = (volatile uint32_t *)addr;
 	*localAddr = value;
 }

+/**
+ * @brief Read a 32bit word from specific memory address
+ */
 inline uint32_t IO_In32(uintptr_t addr)
 {
 	return *(volatile uint32_t *)addr;
 }

+/**
+ * @brief Swap a byte word bit-wise
+ */
 uint8_t byte_bit_swap(uint8_t byte)
 {
 #ifdef __BITSWAP_TABLE
@@ -68,6 +92,9 @@ uint8_t byte_bit_swap(uint8_t byte)
 #endif
 }

+/**
+ * @brief Swap 32bit word bit-wise
+ */
 uint32_t word_bit_swap(uint32_t word)
 {
 #ifdef __BITSWAP_TABLE
@@ -85,6 +112,9 @@ uint32_t word_bit_swap(uint32_t word)
 #endif
 }

+/**
+ * @brief Count ones in an 32bit word
+ */
 uint32_t count_ones(uint32_t word)
 {
 #ifdef __GNUC__
@@ -101,13 +131,16 @@ uint32_t count_ones(uint32_t word)
 #endif
 }

+/**
+ * @brief Convert fix ;oint number to float number
+ */
 double fix2double(int32_t val, uint8_t frac_bits)
 {
 	return (((double)val) / (BIT(frac_bits)));
 }

 /**
- * Find first set bit in word.
+ * @brief Find first set bit in word.
 */
 uint32_t find_first_set_bit(uint32_t word)
 {
@@ -136,7 +169,7 @@ uint32_t find_first_set_bit(uint32_t word)
 }

 /**
- * Find last set bit in word.
+ * @brief Find last set bit in word.
 */
 uint32_t find_last_set_bit(uint32_t word)
 {
@@ -166,7 +199,7 @@ uint32_t find_last_set_bit(uint32_t word)
 }

 /**
- * Locate the closest element in an array.
+ * @brief Locate the closest element in an array.
 */
 uint32_t find_closest(int32_t val,
 					  const int32_t *array,
@@ -189,7 +222,7 @@ uint32_t find_closest(int32_t val,
 }

 /**
- * Shift the value and apply the specified mask.
+ * @brief Shift the value and apply the specified mask.
 */
 uint32_t field_prep(uint32_t mask, uint32_t val)
 {
@@ -197,7 +230,7 @@ uint32_t field_prep(uint32_t mask, uint32_t val)
 }

 /**
- * Get a field specified by a mask from a word.
+ * @brief Get a field specified by a mask from a word.
 */
 uint32_t field_get(uint32_t mask, uint32_t word)
 {
@@ -205,7 +238,7 @@ uint32_t field_get(uint32_t mask, uint32_t word)
 }

 /**
- * Log base 2 of the given number.
+ * @brief Log base 2 of the given number.
 */
 int32_t log_base_2(uint32_t x)
 {
@@ -213,7 +246,7 @@ int32_t log_base_2(uint32_t x)
 }

 /**
- * Find greatest common divisor of the given two numbers.
+ * @brief Find greatest common divisor of the given two numbers.
 */
 uint32_t greatest_common_divisor(uint32_t a,
 								 uint32_t b)
@@ -232,7 +265,7 @@ uint32_t greatest_common_divisor(uint32_t a,
 }

 /**
- * Calculate best rational approximation for a given fraction.
+ * @brief Calculate best rational approximation for a given fraction.
 */
 void rational_best_approximation(uint32_t given_numerator,
 								 uint32_t given_denominator,
@@ -257,7 +290,7 @@ void rational_best_approximation(uint32_t given_numerator,
 }

 /**
- * Calculate the number of set bits.
+ * @brief Calculate the number of set bits.
 */
 uint32_t hweight8(uint32_t word)
 {
@@ -274,7 +307,7 @@ uint32_t hweight8(uint32_t word)
 }

 /**
- * Calculate the quotient and the remainder of an integer division.
+ * @brief Calculate the quotient and the remainder of an integer division.
 */
 uint64_t do_div(uint64_t *n,
 				uint64_t base)
@@ -288,7 +321,7 @@ uint64_t do_div(uint64_t *n,
 }

 /**
- * Unsigned 64bit divide with 64bit divisor and remainder
+ * @brief Unsigned 64bit divide with 64bit divisor and remainder
 */
 uint64_t div64_u64_rem(uint64_t dividend, uint64_t divisor, uint64_t *remainder)
 {
@@ -298,7 +331,7 @@ uint64_t div64_u64_rem(uint64_t dividend, uint64_t divisor, uint64_t *remainder)
 }

 /**
- * Unsigned 64bit divide with 32bit divisor with remainder
+ * @brief Unsigned 64bit divide with 32bit divisor with remainder
 */
 uint64_t div_u64_rem(uint64_t dividend, uint32_t divisor, uint32_t *remainder)
 {
@@ -308,7 +341,7 @@ uint64_t div_u64_rem(uint64_t dividend, uint32_t divisor, uint32_t *remainder)
 }

 /**
- * Signed 64bit divide with 32bit divisor with remainder
+ * @brief Signed 64bit divide with 32bit divisor with remainder
 */
 int64_t div_s64_rem(int64_t dividend, int32_t divisor, int32_t *remainder)
 {
@@ -317,7 +350,7 @@ int64_t div_s64_rem(int64_t dividend, int32_t divisor, int32_t *remainder)
 }

 /**
- * Unsigned 64bit divide with 32bit divisor
+ * @brief Unsigned 64bit divide with 32bit divisor
 */
 uint64_t div_u64(uint64_t dividend, uint32_t divisor)
 {
@@ -327,7 +360,7 @@ uint64_t div_u64(uint64_t dividend, uint32_t divisor)
 }

 /**
- * Signed 64bit divide with 32bit divisor
+ * @brief Signed 64bit divide with 32bit divisor
 */
 int64_t div_s64(int64_t dividend, int32_t divisor)
 {
@@ -336,7 +369,7 @@ int64_t div_s64(int64_t dividend, int32_t divisor)
 }

 /**
- * Converts from string to int32_t
+ * @brief Converts from string to int32_t
 * @param *str
 * @return int32_t
 */
@@ -352,7 +385,7 @@ int32_t str_to_int32(const char *str)
 }

 /**
- * Converts from string to uint32_t
+ * @brief Converts from string to uint32_t
 * @param *str
 * @return uint32_t
 */
@@ -366,3 +399,5 @@ uint32_t srt_to_uint32(const char *str)
 	else
 		return value;
 }
+
+/** @} */