add some missing doxygen annotation for libosmocore functions

7 files changed, 75 insertions, 11 deletions

diff --git a/src/bits.c b/src/bits.c
index a159fc96..f3453e5c 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -128,7 +128,16 @@ int osmo_pbit2ubit_ext(ubit_t *out, unsigned int out_ofs,
 	return out_ofs + num_bits;
 }
 
-/* generalized bit reversal function, Chapter 7 "Hackers Delight" */
+/*! \brief generalized bit reversal function
+ *  \param[in] x the 32bit value to be reversed
+ *  \param[in] k the type of reversal requested
+ *  \returns the reversed 32bit dword
+ *
+ * This function reverses the bit order within a 32bit word. Depending
+ * on "k", it either reverses all bits in a 32bit dword, or the bytes in
+ * the dword, or the bits in each byte of a dword, or simply swaps the
+ * two 16bit words in a dword.  See Chapter 7 "Hackers Delight"
+ */
 uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k)
 {
 	if (k &  1) x = (x & 0x55555555) <<  1 | (x & 0xAAAAAAAA) >>  1;
@@ -140,7 +149,12 @@ uint32_t osmo_bit_reversal(uint32_t x, enum osmo_br_mode k)
 	return x;
 }
 
-/* generalized bit reversal function, Chapter 7 "Hackers Delight" */
+/*! \brief reverse the bit-order in each byte of a dword
+ *  \param[in] x 32bit input value
+ *  \returns 32bit value where bits of each byte have been reversed
+ *
+ * See Chapter 7 "Hackers Delight"
+ */
 uint32_t osmo_revbytebits_32(uint32_t x)
 {
 	x = (x & 0x55555555) <<  1 | (x & 0xAAAAAAAA) >>  1;
@@ -150,6 +164,12 @@ uint32_t osmo_revbytebits_32(uint32_t x)
 	return x;
 }
 
+/*! \brief reverse the bit order in a byte
+ *  \param[in] x 8bit input value
+ *  \returns 8bit value where bits order has been reversed
+ *
+ * See Chapter 7 "Hackers Delight"
+ */
 uint32_t osmo_revbytebits_8(uint8_t x)
 {
 	x = (x & 0x55) <<  1 | (x & 0xAA) >>  1;
@@ -159,6 +179,12 @@ uint32_t osmo_revbytebits_8(uint8_t x)
 	return x;
 }
 
+/*! \brief reverse bit-order of each byte in a buffer
+ *  \param buf buffer containing bytes to be bit-reversed
+ *  \param[in] length of buffer in bytes
+ *
+ *  This function reverses the bits in each byte of the buffer
+ */
 void osmo_revbytebits_buf(uint8_t *buf, int len)
 {
 	unsigned int i;
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index ce722da9..77ab0c6e 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -182,7 +182,18 @@ int gsmtap_source_init_fd(const char *host, uint16_t port)
 				OSMO_SOCK_F_CONNECT);
 }
 
-/*! \brief Add a local sink to an existing GSMTAP source and return fd */
+/*! \brief Add a local sink to an existing GSMTAP source and return fd
+ *  \param[in] gsmtap_fd file descriptor of the gsmtap socket
+ *  \returns file descriptor of locally bound receive socket
+ *
+ *  In case the GSMTAP socket is connected to a local destination
+ *  IP/port, this function creates a corresponding receiving socket
+ *  bound to that destination IP + port.
+ *
+ *  In case the gsmtap socket is not connected to a local IP/port, or
+ *  creation of the receiving socket fails, a negative error code is
+ *  returned.
+ */
 int gsmtap_source_add_sink_fd(int gsmtap_fd)
 {
 	struct sockaddr_storage ss;
@@ -360,3 +371,5 @@ struct gsmtap_inst *gsmtap_source_init(const char *host, uint16_t port,
 }
 
 #endif /* HAVE_SYS_SOCKET_H */
+
+/*! @} */
diff --git a/src/logging.c b/src/logging.c
index f58265f7..1b94ec0b 100644
--- a/src/logging.c
+++ b/src/logging.c
@@ -108,6 +108,7 @@ static const struct log_info_cat internal_cat[OSMO_NUM_DLIB] = {
 	},
 };
 
+/*! \brief descriptive string for each log level */
 /* You have to keep this in sync with the structure loglevel_strs. */
 const char *loglevel_descriptions[LOGLEVEL_DEFS+1] = {
 	"Log simply everything",
@@ -318,6 +319,7 @@ void osmo_vlogp(int subsys, int level, const char *file, int line,
 	}
 }
 
+/*! \brief logging function used by DEBUGP() macro */
 void logp(int subsys, const char *file, int line, int cont,
 	  const char *format, ...)
 {
@@ -328,6 +330,7 @@ void logp(int subsys, const char *file, int line, int cont,
 	va_end(ap);
 }
 
+/*! \brief logging function used by LOGP() macro */
 void logp2(int subsys, unsigned int level, const char *file, int line, int cont, const char *format, ...)
 {
 	va_list ap;
@@ -431,6 +434,12 @@ void log_set_log_level(struct log_target *target, int log_level)
 	target->loglevel = log_level;
 }
 
+/*! \brief Set a category filter on a given log target
+ *  \param[in] target Log target to be affected
+ *  \param[in] category Log category to be affected
+ *  \param[in] enable whether to enable or disable the filter
+ *  \param[in] level Log level of the filter
+ */
 void log_set_category_filter(struct log_target *target, int category,
 			       int enable, int level)
 {
diff --git a/src/panic.c b/src/panic.c
index be644ff1..84bab33b 100644
--- a/src/panic.c
+++ b/src/panic.c
@@ -80,3 +80,4 @@ void osmo_set_panic_handler(osmo_panic_handler_t h)
 	osmo_panic_handler = h;
 }
 
+/*! @} */
diff --git a/src/plugin.c b/src/plugin.c
index 998bca35..52887acf 100644
--- a/src/plugin.c
+++ b/src/plugin.c
@@ -20,6 +20,11 @@
  *
  */
 
+/*! \file plugin.c
+ *  \brief Routines for loading and managing shared library plug-ins.
+ */
+
+
 #include "../config.h"
 
 #if HAVE_DLFCN_H
@@ -32,6 +37,10 @@
 
 #include <osmocom/core/plugin.h>
 
+/*! \brief Load all plugins available in given directory
+ *  \param[in] directory full path name of directory containing plug-ins
+ *  \returns number of plugins loaded in case of success, negative in case of error
+ */
 int osmo_plugin_load_all(const char *directory)
 {
 	unsigned int num = 0;
diff --git a/src/timer.c b/src/timer.c
index 6d4abc26..98cbf6e6 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -154,7 +154,9 @@ int osmo_timer_remaining(const struct osmo_timer_list *timer,
 	return 0;
 }
 
-/*
+/*! \brief Determine time between now and the nearest timer
+ *  \returns pointer to timeval of nearest timer, NULL if there is none
+ *
  * if we have a nearest time return the delta between the current
  * time and the time of the nearest timer.
  * If the nearest timer timed out return NULL and then we will
@@ -184,9 +186,7 @@ static void update_nearest(struct timeval *cand, struct timeval *current)
 	}
 }
 
-/*
- * Find the nearest time and update s_nearest_time
- */
+/*! \brief Find the nearest time and update nearest_p */
 void osmo_timers_prepare(void)
 {
 	struct rb_node *node;
@@ -204,9 +204,7 @@ void osmo_timers_prepare(void)
 	}
 }
 
-/*
- * fire all timers... and remove them
- */
+/*! \brief fire all timers... and remove them */
 int osmo_timers_update(void)
 {
 	struct timeval current_time;
diff --git a/src/utils.c b/src/utils.c
index cf0c9344..c36979c9 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -64,12 +64,20 @@ char osmo_bcd2char(uint8_t bcd)
 		return 'A' + (bcd - 0xa);
 }
 
-/* only works for numbers in ascii */
+/*! \brief Convert number in ASCII to BCD value
+ *  \param[in] c ASCII character
+ *  \returns BCD encoded value of character
+ */
 uint8_t osmo_char2bcd(char c)
 {
 	return c - 0x30;
 }
 
+/*! \brief Parse a string ocntaining hexadecimal digits
+ *  \param[in] str string containing ASCII encoded hexadecimal digits
+ *  \param[out] b output buffer
+ *  \param[in] max_len maximum space in output buffer
+ */
 int osmo_hexparse(const char *str, uint8_t *b, int max_len)
 
 {