From ba6988bd893eb08c54ffdb144700530e3a683d6e Mon Sep 17 00:00:00 2001
From: Harald Welte <laforge@gnumonks.org>
Date: Wed, 17 Aug 2011 12:46:48 +0200
Subject: some more doxygen work (include the notion of modules)

---
 src/bitvec.c | 53 ++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 42 insertions(+), 11 deletions(-)

(limited to 'src/bitvec.c')

diff --git a/src/bitvec.c b/src/bitvec.c
index 4fd38349..8a086b81 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -20,6 +20,13 @@
  *
  */
 
+/*! \addtogroup bitvec
+ *  @{
+ */
+
+/*! \file bitvec.c
+ *  \brief Osmocom bit vector abstraction
+ */
 
 #include <errno.h>
 #include <stdint.h>
@@ -59,7 +66,11 @@ static uint8_t bitval2mask(enum bit_value bit, uint8_t bitnum)
 	return bitval;
 }
 
-/* check if the bit is 0 or 1 for a given position inside a bitvec */
+/*! \brief check if the bit is 0 or 1 for a given position inside a bitvec
+ *  \param[in] bv the bit vector on which to check
+ *  \param[in] bitnr the bit number inside the bit vector to check
+ *  \returns 
+ */
 enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
 {
 	unsigned int bytenum = bytenum_from_bitnum(bitnr);
@@ -77,7 +88,10 @@ enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
 	return ZERO;
 }
 
-/* check if the bit is L or H for a given position inside a bitvec */
+/*! \brief check if the bit is L or H for a given position inside a bitvec
+ *  \param[in] bv the bit vector on which to check
+ *  \param[in] bitnr the bit number inside the bit vector to check
+ */
 enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
 					unsigned int bitnr)
 {
@@ -96,7 +110,11 @@ enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
 	return L;
 }
 
-/* get the Nth set bit inside the bit vector */
+/*! \brief get the Nth set bit inside the bit vector
+ *  \param[in] bv the bit vector to use
+ *  \param[in] n the bit number to get
+ *  \returns the bit number (offset) of the Nth set bit in \a bv
+ */
 unsigned int bitvec_get_nth_set_bit(const struct bitvec *bv, unsigned int n)
 {
 	unsigned int i, k = 0;
@@ -112,7 +130,11 @@ unsigned int bitvec_get_nth_set_bit(const struct bitvec *bv, unsigned int n)
 	return 0;
 }
 
-/* set the bit at a given position inside a bitvec */
+/*! \brief set a bit at given position in a bit vector
+ *  \param[in] bv bit vector on which to operate
+ *  \param[in] bitnum number of bit to be set
+ *  \param[in] bit value to which the bit is to be set
+ */
 int bitvec_set_bit_pos(struct bitvec *bv, unsigned int bitnr,
 			enum bit_value bit)
 {
@@ -134,7 +156,10 @@ int bitvec_set_bit_pos(struct bitvec *bv, unsigned int bitnr,
 	return 0;
 }
 
-/* set the next bit inside a bitvec */
+/*! \brief set the next bit inside a bitvec
+ *  \param[in] bv bit vector to be used
+ *  \param[in] bit value of the bit to be set
+ */
 int bitvec_set_bit(struct bitvec *bv, enum bit_value bit)
 {
 	int rc;
@@ -146,7 +171,7 @@ int bitvec_set_bit(struct bitvec *bv, enum bit_value bit)
 	return rc;
 }
 
-/* get the next bit (low/high) inside a bitvec */
+/*! \brief get the next bit (low/high) inside a bitvec */
 int bitvec_get_bit_high(struct bitvec *bv)
 {
 	int rc;
@@ -158,7 +183,11 @@ int bitvec_get_bit_high(struct bitvec *bv)
 	return rc;
 }
 
-/* set multiple bits (based on array of bitvals) at current pos */
+/*! \brief set multiple bits (based on array of bitvals) at current pos
+ *  \param[in] bv bit vector
+ *  \param[in] bits array of \ref bit_value
+ *  \param[in] count number of bits to set
+ */
 int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, int count)
 {
 	int i, rc;
@@ -172,7 +201,7 @@ int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, int count)
 	return 0;
 }
 
-/* set multiple bits (based on numeric value) at current pos */
+/*! \brief set multiple bits (based on numeric value) at current pos */
 int bitvec_set_uint(struct bitvec *bv, unsigned int ui, int num_bits)
 {
 	int i, rc;
@@ -189,7 +218,7 @@ int bitvec_set_uint(struct bitvec *bv, unsigned int ui, int num_bits)
 	return 0;
 }
 
-/* get multiple bits (based on numeric value) from current pos */
+/*! \brief get multiple bits (based on numeric value) from current pos */
 int bitvec_get_uint(struct bitvec *bv, int num_bits)
 {
 	int i;
@@ -207,7 +236,7 @@ int bitvec_get_uint(struct bitvec *bv, int num_bits)
 	return ui;
 }
 
-/* pad all remaining bits up to num_bits */
+/*! \brief pad all remaining bits up to num_bits */
 int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
 {
 	unsigned int i;
@@ -218,7 +247,7 @@ int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
 	return 0;
 }
 
-/* find first bit set in bit vector */
+/*! \brief find first bit set in bit vector */
 int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
 			enum bit_value val)
 {
@@ -231,3 +260,5 @@ int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
 
 	return -1;
 }
+
+/*! }@ */
-- 
cgit v1.2.3