doxygen: Add docs for rate_ctr

2 files changed, 53 insertions, 26 deletions

diff --git a/include/osmocom/core/rate_ctr.h b/include/osmocom/core/rate_ctr.h
index ebb8646c..c38e5f9b 100644
--- a/include/osmocom/core/rate_ctr.h
+++ b/include/osmocom/core/rate_ctr.h
@@ -1,80 +1,88 @@
 #ifndef _RATE_CTR_H
 #define _RATE_CTR_H
 
+/*! \defgroup rate_ctr Rate counters
+ *  @{
+ */
+
+/*! \file rate_ctr.h */
+
 #include <stdint.h>
 
 #include <osmocom/core/linuxlist.h>
 
+/*! \brief Number of rate counter intervals */
 #define RATE_CTR_INTV_NUM	4
 
+/*! \brief Rate counter interval */
 enum rate_ctr_intv {
-	RATE_CTR_INTV_SEC,
-	RATE_CTR_INTV_MIN,
-	RATE_CTR_INTV_HOUR,
-	RATE_CTR_INTV_DAY,
+	RATE_CTR_INTV_SEC,	/*!< \brief last second */
+	RATE_CTR_INTV_MIN,	/*!< \brief last minute */
+	RATE_CTR_INTV_HOUR,	/*!< \brief last hour */
+	RATE_CTR_INTV_DAY,	/*!< \brief last day */
 };
 
-/* for each of the intervals, we keep the following values */
+/*! \brief data we keep for each of the intervals */
 struct rate_ctr_per_intv {
-	uint64_t last;
-	uint64_t rate;
+	uint64_t last;		/*!< \brief counter value in last interval */
+	uint64_t rate;		/*!< \brief counter rate */
 };
 
-/* for each actual value, we keep the following data */
+/*! \brief data we keep for each actual value */
 struct rate_ctr {
-	uint64_t current;
+	uint64_t current;	/*!< \brief current value */
+	/*! \brief per-interval data */
 	struct rate_ctr_per_intv intv[RATE_CTR_INTV_NUM];
 };
 
+/*! \brief rate counter description */
 struct rate_ctr_desc {
-	const char *name;
-	const char *description;
+	const char *name;	/*!< \brief name of the counter */
+	const char *description;/*!< \brief description of the counter */
 };
 
-/* Describe a counter group class */
+/*! \brief description of a rate counter group */
 struct rate_ctr_group_desc {
-	/* The prefix to the name of all counters in this group */
+	/*! \brief The prefix to the name of all counters in this group */
 	const char *group_name_prefix;
-	/* The human-readable description of the group */
+	/*! \brief The human-readable description of the group */
 	const char *group_description;
-	/* The number of counters in this group */
+	/*! \brief The number of counters in this group */
 	const unsigned int num_ctr;
-	/* Pointer to array of counter names */
+	/*! \brief Pointer to array of counter names */
 	const struct rate_ctr_desc *ctr_desc;
 };
 
-/* One instance of a counter group class */
+/*! \brief One instance of a counter group class */
 struct rate_ctr_group {
-	/* Linked list of all counter groups in the system */
+	/*! \brief Linked list of all counter groups in the system */
 	struct llist_head list;
-	/* Pointer to the counter group class */
+	/*! \brief Pointer to the counter group class */
 	const struct rate_ctr_group_desc *desc;
-	/* The index of this ctr_group within its class */
+	/*! \brief The index of this ctr_group within its class */
 	unsigned int idx;
-	/* Actual counter structures below */
+	/*! \brief Actual counter structures below */
 	struct rate_ctr ctr[0];
 };
 
-/* Allocate a new group of counters according to description */
 struct rate_ctr_group *rate_ctr_group_alloc(void *ctx,
 					    const struct rate_ctr_group_desc *desc,
 					    unsigned int idx);
 
-/* Free the memory for the specified group of counters */
 void rate_ctr_group_free(struct rate_ctr_group *grp);
 
-/* Add a number to the counter */
 void rate_ctr_add(struct rate_ctr *ctr, int inc);
 
-/* Increment the counter by 1 */
+/*! \brief Increment the counter by 1 */
 static inline void rate_ctr_inc(struct rate_ctr *ctr)
 {
 	rate_ctr_add(ctr, 1);
 }
 
-/* Initialize the counter module */
 int rate_ctr_init(void *tall_ctx);
 
 struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx);
 const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name);
+
+/*! }@ */
 #endif /* RATE_CTR_H */
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 6d771a44..24166b84 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -20,6 +20,13 @@
  *
  */
 
+/*! \addtogroup rate_ctr
+ *  @{
+ */
+
+/*! \file rate_ctr.c */
+
+
 #include <stdint.h>
 #include <string.h>
 
@@ -33,6 +40,11 @@ static LLIST_HEAD(rate_ctr_groups);
 
 static void *tall_rate_ctr_ctx;
 
+/*! \brief Allocate a new group of counters according to description
+ *  \param[in] ctx \ref talloc context
+ *  \param[in] desc Rate counter group description
+ *  \param[in] idx Index of new counter group
+ */
 struct rate_ctr_group *rate_ctr_group_alloc(void *ctx,
 					    const struct rate_ctr_group_desc *desc,
 					    unsigned int idx)
@@ -58,12 +70,14 @@ struct rate_ctr_group *rate_ctr_group_alloc(void *ctx,
 	return group;
 }
 
+/*! \brief Free the memory for the specified group of counters */
 void rate_ctr_group_free(struct rate_ctr_group *grp)
 {
 	llist_del(&grp->list);
 	talloc_free(grp);
 }
 
+/*! \brief Add a number to the counter */
 void rate_ctr_add(struct rate_ctr *ctr, int inc)
 {
 	ctr->current += inc;
@@ -117,6 +131,7 @@ static void rate_ctr_timer_cb(void *data)
 	osmo_timer_schedule(&rate_ctr_timer, 1, 0);
 }
 
+/*! \brief Initialize the counter module */
 int rate_ctr_init(void *tall_ctx)
 {
 	tall_rate_ctr_ctx = tall_ctx;
@@ -126,6 +141,7 @@ int rate_ctr_init(void *tall_ctx)
 	return 0;
 }
 
+/*! \brief Search for counter group based on group name and index */
 struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx)
 {
 	struct rate_ctr_group *ctrg;
@@ -142,6 +158,7 @@ struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const un
 	return NULL;
 }
 
+/*! \brief Search for counter group based on group name */
 const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name)
 {
 	int i;
@@ -159,3 +176,5 @@ const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, c
 	}
 	return NULL;
 }
+
+/*! }@ */