start to add doxygen documentation to libosmocore headers

1 files changed, 38 insertions, 10 deletions

diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index eb22d07c..9f8e1fb5 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -3,9 +3,13 @@
 
 #include <stdint.h>
 
-typedef int8_t  sbit_t;		/* soft bit (-127...127) */
-typedef uint8_t ubit_t;		/* unpacked bit (0 or 1) */
-typedef uint8_t pbit_t;		/* packed bis (8 bits in a byte) */
+/*! \file bits.h
+ *  \brief Osmocom bit level support code
+ */
+
+typedef int8_t  sbit_t;		/*!< \brief soft bit (-127...127) */
+typedef uint8_t ubit_t;		/*!< \brief unpacked bit (0 or 1) */
+typedef uint8_t pbit_t;		/*!< \brief packed bis (8 bits in a byte) */
 
 /*
    NOTE on the endianess of pbit_t:
@@ -13,7 +17,9 @@ typedef uint8_t pbit_t;		/* packed bis (8 bits in a byte) */
    Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
 */
 
-/* determine how many bytes we would need for 'num_bits' packed bits */
+/*! \brief determine how many bytes we would need for \a num_bits packed bits
+ *  \param[in] num_bits Number of packed bits
+ */
 static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
 {
 	unsigned int pbit_bytesize = num_bits / 8;
@@ -24,20 +30,42 @@ static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
 	return pbit_bytesize;
 }
 
-/* convert unpacked bits to packed bits, return length in bytes */
+/*! \brief convert unpacked bits to packed bits, return length in bytes
+ *  \param[out] out output buffer of packed bits
+ *  \param[in] in input buffer of unpacked bits
+ *  \param[in] num_bits number of bits
+ */
 int osmo_ubit2pbit(pbit_t *out, const ubit_t *in, unsigned int num_bits);
 
-/* convert packed bits to unpacked bits, return length in bytes */
+/*! \brief convert packed bits to unpacked bits, return length in bytes
+ *  \param[out] out output buffer of unpacked bits
+ *  \param[in] in input buffer of packed bits
+ *  \param[in] num_bits number of bits
+ */
 int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits);
 
-/* convert unpacked bits to packed bits (extended options but slower),
- * return length in bytes (max written ofs of output buffer + 1) */
+/*! \brief convert unpacked bits to packed bits (extended options)
+ *  \param[out] out output buffer of packed bits
+ *  \param[in] out_ofs offset into output buffer
+ *  \param[in] in input buffer of unpacked bits
+ *  \param[in] in_ofs offset into input buffer
+ *  \param[in] num_bits number of bits
+ *  \param[in] lsb_mode Encode bits in LSB orde instead of MSB
+ *  \returns length in bytes (max written offset of output buffer + 1)
+ */
 int osmo_ubit2pbit_ext(pbit_t *out, unsigned int out_ofs,
                        const ubit_t *in, unsigned int in_ofs,
                        unsigned int num_bits, int lsb_mode);
 
-/* convert packed bits to unpacked bits (extended options but slower),
- * return length in bytes (max written ofs of output buffer + 1) */
+/*! \brief convert packed bits to unpacked bits (extended options)
+ *  \param[out] out output buffer of unpacked bits
+ *  \param[in] out_ofs offset into output buffer
+ *  \param[in] in input buffer of packed bits
+ *  \param[in] in_ofs offset into input buffer
+ *  \param[in] num_bits number of bits
+ *  \param[in] lsb_mode Encode bits in LSB orde instead of MSB
+ *  \returns length in bytes (max written offset of output buffer + 1)
+ */
 int osmo_pbit2ubit_ext(ubit_t *out, unsigned int out_ofs,
                        const pbit_t *in, unsigned int in_ofs,
                        unsigned int num_bits, int lsb_mode);