Update doxygen annotations in libosmocore

This adds and improves doxygen API descriptions all over libosmocore,
reducing the 'white spots' that don't have any documentation.

18 files changed, 212 insertions, 47 deletions

diff --git a/src/application.c b/src/application.c
index 9c3fe52b..8a325c8a 100644
--- a/src/application.c
+++ b/src/application.c
@@ -40,7 +40,7 @@
  * a multi-threaded context, you have to add your own locking.
  *
  * \section sec_copyright Copyright and License
- * Copyright © 2008-2011 - Harald Welte, Holger Freyther and contributors\n
+ * Copyright © 2008-2016 - Harald Welte, Holger Freyther and contributors\n
  * All rights reserved. \n\n
  * The source code of libosmocore is licensed under the terms of the GNU
  * General Public License as published by the Free Software Foundation;
diff --git a/src/backtrace.c b/src/backtrace.c
index 5b93becb..6cd798c5 100644
--- a/src/backtrace.c
+++ b/src/backtrace.c
@@ -70,6 +70,8 @@ void osmo_generate_backtrace(void)
 }
 
 /*! \brief Generate and log a call back-trace
+ *  \param[in] subsys Logging sub-system
+ *  \param[in] level Logging level
  *
  * This function will generate a function call back-trace of the
  * current process and log it to the specified subsystem and
diff --git a/src/bitcomp.c b/src/bitcomp.c
index bf359274..8b3090e6 100644
--- a/src/bitcomp.c
+++ b/src/bitcomp.c
@@ -232,9 +232,9 @@ static const unsigned t4_make_up[2][15] = {
 
 /*! \brief Attempt to decode compressed bit vector
  *
- * Return length of RLE according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2
- * or -1 if no applicable RLE found
- * N. B: we need explicit bit length to make decoding unambiguous
+ *  \return length of RLE according to modified ITU-T T.4 from TS 44.060
+ *  Table 9.1.10.2 or -1 if no applicable RLE found N. B: we need
+ *  explicit bit length to make decoding unambiguous
 */
 static inline int t4_rle_term(unsigned w, bool b, unsigned bits)
 {
@@ -256,8 +256,9 @@ static inline int t4_rle_makeup(unsigned w, bool b, unsigned bits)
 
 /*! \brief Make-up codes for a given length
  *
- * Return proper make-up code word for an uninterrupted sequence of b bits
- * of length len according to modified ITU-T T.4 from TS 44.060 Table 9.1.10.2 */
+ *  \return Return proper make-up code word for an uninterrupted
+ *  sequence of b bits of length len according to modified ITU-T T.4
+ *  from TS 44.060 Table 9.1.10.2 */
 static inline int t4_rle(struct bitvec *bv, unsigned len, bool b)
 {
 	if (len >= 960) {
@@ -384,7 +385,7 @@ static inline enum dec_state _t4_step(struct bitvec *v, uint16_t w, bool b, unsi
  *  \param[in] in bit vector with encoded data
  *  \param[in] cc color code (whether decoding should start with 1 or 0)
  *  \param[out] out the bit vector to store result into
- * returns 0 on success, negative value otherwise
+ *  \return 0 on success, negative value otherwise
  */
 int osmo_t4_decode(const struct bitvec *in, bool cc, struct bitvec *out)
 {
@@ -437,7 +438,8 @@ int osmo_t4_decode(const struct bitvec *in, bool cc, struct bitvec *out)
 /*! \brief encode bit vector in-place using T4 encoding
  *  Assumes MSB first encoding.
  *  \param[in] bv bit vector to be encoded
- * returns color code (if the encoding started with 0 or 1) or -1 on failure (encoded is bigger than original)
+ *  \return color code (if the encoding started with 0 or 1) or -1 on
+ *  failure (encoded is bigger than original)
  */
 int osmo_t4_encode(struct bitvec *bv)
 {
diff --git a/src/bits.c b/src/bits.c
index 48314af4..569a10f0 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -89,6 +89,7 @@ void osmo_sbit2ubit(ubit_t *out, const sbit_t *in, unsigned int num_bits)
  *  \param[out] out output buffer of unpacked bits
  *  \param[in] in input buffer of packed bits
  *  \param[in] num_bits number of bits
+ *  \return number of bytes used in \ref out
  */
 int osmo_pbit2ubit(ubit_t *out, const pbit_t *in, unsigned int num_bits)
 {
diff --git a/src/bitvec.c b/src/bitvec.c
index a92fd716..88343c4f 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -75,7 +75,7 @@ static uint8_t bitval2mask(enum bit_value bit, uint8_t bitnum)
 /*! \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 
+ *  \return value of the requested bit
  */
 enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
 {
@@ -97,6 +97,7 @@ enum bit_value bitvec_get_bit_pos(const struct bitvec *bv, unsigned int bitnr)
 /*! \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
+ *  \return value of the requested bit
  */
 enum bit_value bitvec_get_bit_pos_high(const struct bitvec *bv,
 					unsigned int bitnr)
@@ -179,7 +180,8 @@ int bitvec_set_bit(struct bitvec *bv, enum bit_value bit)
 	return rc;
 }
 
-/*! \brief get the next bit (low/high) inside a bitvec */
+/*! \brief get the next bit (low/high) inside a bitvec
+ *  \return value of th next bit in the vector */
 int bitvec_get_bit_high(struct bitvec *bv)
 {
 	int rc;
@@ -195,7 +197,7 @@ int bitvec_get_bit_high(struct bitvec *bv)
  *  \param[in] bv bit vector
  *  \param[in] bits array of \ref bit_value
  *  \param[in] count number of bits to set
- */
+ *  \return 0 on success; negative in case of error */
 int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, unsigned int count)
 {
 	int i, rc;
@@ -209,7 +211,8 @@ int bitvec_set_bits(struct bitvec *bv, enum bit_value *bits, unsigned int count)
 	return 0;
 }
 
-/*! \brief set multiple bits (based on numeric value) at current pos */
+/*! \brief set multiple bits (based on numeric value) at current pos
+ *  \return 0 in case of success; negative in case of error */
 int bitvec_set_uint(struct bitvec *bv, unsigned int ui, unsigned int num_bits)
 {
 	int rc;
@@ -226,7 +229,8 @@ int bitvec_set_uint(struct bitvec *bv, unsigned int ui, unsigned int num_bits)
 	return 0;
 }
 
-/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side) */
+/*! \brief get multiple bits (num_bits) from beginning of vector (MSB side)
+ *  \return 16bit signed integer retrieved from bit vector */
 int16_t bitvec_get_int16_msb(const struct bitvec *bv, unsigned int num_bits)
 {
 	if (num_bits > 15 || bv->cur_bit < num_bits)
@@ -238,7 +242,8 @@ int16_t bitvec_get_int16_msb(const struct bitvec *bv, unsigned int num_bits)
 	return osmo_load16be(bv->data) >> (16 - num_bits);
 }
 
-/*! \brief get multiple bits (based on numeric value) from current pos */
+/*! \brief get multiple bits (based on numeric value) from current pos
+ *  \return integer value retrieved from bit vector */
 int bitvec_get_uint(struct bitvec *bv, unsigned int num_bits)
 {
 	int i;
@@ -257,7 +262,7 @@ int bitvec_get_uint(struct bitvec *bv, unsigned int num_bits)
 }
 
 /*! \brief fill num_bits with \fill starting from the current position
- * returns 0 on success, negative otherwise (out of vector boundary)
+ *  \return 0 on success; negative otherwise (out of vector boundary)
  */
 int bitvec_fill(struct bitvec *bv, unsigned int num_bits, enum bit_value fill)
 {
@@ -269,7 +274,8 @@ int bitvec_fill(struct bitvec *bv, unsigned int num_bits, enum bit_value fill)
 	return 0;
 }
 
-/*! \brief pad all remaining bits up to num_bits */
+/*! \brief pad all remaining bits up to num_bits
+ *  \return 0 on success; negative otherwise */
 int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
 {
 	int n = up_to_bit - bv->cur_bit + 1;
@@ -279,7 +285,8 @@ int bitvec_spare_padding(struct bitvec *bv, unsigned int up_to_bit)
 	return bitvec_fill(bv, n, L);
 }
 
-/*! \brief find first bit set in bit vector */
+/*! \brief find first bit set in bit vector
+ *  \return 0 on success; negative otherwise */
 int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
 			enum bit_value val)
 {
@@ -298,6 +305,7 @@ int bitvec_find_bit_pos(const struct bitvec *bv, unsigned int n,
  *  \param[in] bv bit vector
  *  \param[in] bytes array
  *  \param[in] count number of bytes to copy
+ *  \return 0 on success; negative otherwise
  */
 int bitvec_get_bytes(struct bitvec *bv, uint8_t *bytes, unsigned int count)
 {
@@ -333,6 +341,7 @@ int bitvec_get_bytes(struct bitvec *bv, uint8_t *bytes, unsigned int count)
  *  \param[in] bv bit vector
  *  \param[in] bytes array
  *  \param[in] count number of bytes to copy
+ *  \return 0 on success; negative otherwise
  */
 int bitvec_set_bytes(struct bitvec *bv, const uint8_t *bytes, unsigned int count)
 {
@@ -367,6 +376,10 @@ int bitvec_set_bytes(struct bitvec *bv, const uint8_t *bytes, unsigned int count
 	return 0;
 }
 
+/*! \brief Allocate a bit vector
+ *  \param[in] size Number of bits in the vector
+ *  \param[in] ctx Context from which to allocate
+ *  \return pointer to allocated vector; NULL in case of error */
 struct bitvec *bitvec_alloc(unsigned int size, TALLOC_CTX *ctx)
 {
 	struct bitvec *bv = talloc_zero(ctx, struct bitvec);
@@ -384,12 +397,18 @@ struct bitvec *bitvec_alloc(unsigned int size, TALLOC_CTX *ctx)
 	return bv;
 }
 
+/*! \brief Free a bit vector (release its memory)
+ *  \param[in] bit vector to free */
 void bitvec_free(struct bitvec *bv)
 {
 	talloc_free(bv->data);
 	talloc_free(bv);
 }
 
+/*! \brief Export a bit vector to a buffer
+ *  \param[in] bitvec (unpacked bits)
+ *  \param[out] buffer for the unpacked bits
+ *  \return number of bytes (= bits) copied */
 unsigned int bitvec_pack(const struct bitvec *bv, uint8_t *buffer)
 {
 	unsigned int i = 0;
@@ -399,6 +418,10 @@ unsigned int bitvec_pack(const struct bitvec *bv, uint8_t *buffer)
 	return i;
 }
 
+/*! \brief Copy buffer of unpacked bits into bit vector
+ *  \param[in] buffer unpacked input bits
+ *  \param[out] bv unpacked bit vector
+ *  \return number of bytes (= bits) copied */
 unsigned int bitvec_unpack(struct bitvec *bv, const uint8_t *buffer)
 {
 	unsigned int i = 0;
@@ -408,7 +431,11 @@ unsigned int bitvec_unpack(struct bitvec *bv, const uint8_t *buffer)
 	return i;
 }
 
-
+/*! \brief read hexadecimap string into a bit vector
+ *  \param[in] src string containing hex digits
+ *  \param[out] bv unpacked bit vector
+ *  \return 0 in case of success; 1 in case of error
+ */
 int bitvec_unhex(struct bitvec *bv, const char *src)
 {
 	unsigned i;
@@ -472,7 +499,9 @@ int bitvec_write_field(struct bitvec *bv, unsigned int *write_index, uint64_t va
 	return 0;
 }
 
-/*! \brief convert enum to corresponding character */
+/*! \brief convert enum to corresponding character
+ *  \param v input value (bit)
+ *  \return single character, either 0, 1, L or H */
 char bit_value_to_char(enum bit_value v)
 {
 	switch (v) {
diff --git a/src/crc16.c b/src/crc16.c
index 2741cf53..9dd46727 100644
--- a/src/crc16.c
+++ b/src/crc16.c
@@ -10,7 +10,7 @@
 
 #include <osmocom/core/crc16.h>
 
-/** CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
+/*! \brief CRC table for the CRC-16. The poly is 0x8005 (x^16 + x^15 + x^2 + 1) */
 uint16_t const osmo_crc16_table[256] = {
 	0x0000, 0xC0C1, 0xC181, 0x0140, 0xC301, 0x03C0, 0x0280, 0xC241,
 	0xC601, 0x06C0, 0x0780, 0xC741, 0x0500, 0xC5C1, 0xC481, 0x0440,
@@ -46,13 +46,11 @@ uint16_t const osmo_crc16_table[256] = {
 	0x8201, 0x42C0, 0x4380, 0x8341, 0x4100, 0x81C1, 0x8081, 0x4040
 };
 
-/**
- * crc16 - compute the CRC-16 for the data buffer
- * @crc:	previous CRC value
- * @buffer:	data pointer
- * @len:	number of bytes in the buffer
- *
- * Returns the updated CRC value.
+/*! \brief compute the CRC-16 for the data buffer
+ *  \param crc[in] previous CRC value
+ *  \param buffer[in] data pointer
+ *  \param len[in] number of bytes in input \ref buffer
+ *  \return updated CRC value
  */
 uint16_t osmo_crc16(uint16_t crc, uint8_t const *buffer, size_t len)
 {
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 82690a9c..7a63771a 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -99,6 +99,7 @@ uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t link_id)
  *  \param[in] snr Signal/Noise Ratio (SNR)
  *  \param[in] data Pointer to data buffer
  *  \param[in] len Length of \ref data
+ *  \return dynamically allocated message buffer containing data
  *
  * This function will allocate a new msgb and fill it with a GSMTAP
  * header containing the information
@@ -145,6 +146,7 @@ struct msgb *gsmtap_makemsg_ex(uint8_t type, uint16_t arfcn, uint8_t ts, uint8_t
  *  \param[in] snr Signal/Noise Ratio (SNR)
  *  \param[in] data Pointer to data buffer
  *  \param[in] len Length of \ref data
+ *  \return message buffer or NULL in case of error
  *
  * This function will allocate a new msgb and fill it with a GSMTAP
  * header containing the information
@@ -165,6 +167,7 @@ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type,
 /*! \brief Create a new (sending) GSMTAP source socket 
  *  \param[in] host host name or IP address in string format
  *  \param[in] port UDP port number in host byte order
+ *  \return file descriptor of the new socket
  *
  * Opens a GSMTAP source (sending) socket, conncet it to host/port and
  * return resulting fd.  If \a host is NULL, the destination address
@@ -217,6 +220,7 @@ int gsmtap_source_add_sink_fd(int gsmtap_fd)
 /*! \brief Send a \ref msgb through a GSMTAP source
  *  \param[in] gti GSMTAP instance
  *  \param[in] msg message buffer
+ *  \return 0 in case of success; negative in case of error
  */
 int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg)
 {
@@ -312,7 +316,21 @@ static int gsmtap_sink_fd_cb(struct osmo_fd *fd, unsigned int flags)
 	return 0;
 }
 
-/*! \brief Add a local sink to an existing GSMTAP source instance */
+/*! \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.
+ *
+ *  The file descriptor of the receiving socket is automatically added
+ *  to the libosmocore select() handling.
+ */
 int gsmtap_source_add_sink(struct gsmtap_inst *gti)
 {
 	int fd;
@@ -340,6 +358,7 @@ int gsmtap_source_add_sink(struct gsmtap_inst *gti)
  *  \param[in] host host name or IP address in string format
  *  \param[in] port UDP port number in host byte order
  *  \param[in] ofd_wq_mode Register \ref osmo_wqueue (1) or not (0)
+ *  \return callee-allocated \ref gsmtap_inst
  *
  * Open GSMTAP source (sending) socket, connect it to host/port,
  * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue
diff --git a/src/logging.c b/src/logging.c
index 4d6fd40d..b2f8d437 100644
--- a/src/logging.c
+++ b/src/logging.c
@@ -142,13 +142,19 @@ static int subsys_lib2index(int subsys)
 	return (subsys * -1) + (osmo_log_info->num_cat_user-1);
 }
 
-/*! \brief Parse a human-readable log level into a numeric value */
+/*! \brief Parse a human-readable log level into a numeric value
+ *  \param lvl[in] zero-terminated string containing log level name
+ *  \returns numeric log level
+ */
 int log_parse_level(const char *lvl)
 {
 	return get_string_value(loglevel_strs, lvl);
 }
 
-/*! \brief convert a numeric log level into human-readable string */
+/*! \brief convert a numeric log level into human-readable string
+ *  \param lvl[in] numeric log level
+ *  \returns zero-terminated string (log level name)
+ */
 const char *log_level_str(unsigned int lvl)
 {
 	return get_value_string(loglevel_strs, lvl);
@@ -353,7 +359,14 @@ static inline int check_log_to_target(struct log_target *tar, int subsys, int le
 	return 1;
 }
 
-/*! \brief vararg version of logging function */
+/*! \brief vararg version of logging function
+ *  \param[in] subsys Logging sub-system
+ *  \param[in] level Log level
+ *  \param[in] file name of source code file
+ *  \param[in] cont continuation (1) or new line (0)
+ *  \param[in] format format string
+ *  \param[in] ap vararg-list containing format string arguments
+ */
 void osmo_vlogp(int subsys, int level, const char *file, int line,
 		int cont, const char *format, va_list ap)
 {
@@ -376,7 +389,12 @@ void osmo_vlogp(int subsys, int level, const char *file, int line,
 	}
 }
 
-/*! \brief logging function used by DEBUGP() macro */
+/*! \brief logging function used by DEBUGP() macro
+ *  \param[in] subsys Logging sub-system
+ *  \param[in] file name of source code file
+ *  \param[in] cont continuation (1) or new line (0)
+ *  \param[in] format format string
+ */
 void logp(int subsys, const char *file, int line, int cont,
 	  const char *format, ...)
 {
@@ -387,7 +405,13 @@ void logp(int subsys, const char *file, int line, int cont,
 	va_end(ap);
 }
 
-/*! \brief logging function used by LOGP() macro */
+/*! \brief logging function used by LOGP() macro
+ *  \param[in] subsys Logging sub-system
+ *  \param[in] level Log level
+ *  \param[in] file name of source code file
+ *  \param[in] cont continuation (1) or new line (0)
+ *  \param[in] format format string
+ */
 void logp2(int subsys, unsigned int level, const char *file, int line, int cont, const char *format, ...)
 {
 	va_list ap;
@@ -422,6 +446,7 @@ void log_reset_context(void)
 /*! \brief Set the logging context
  *  \param[in] ctx_nr logging context number
  *  \param[in] value value to which the context is to be set
+ *  \returns 0 in case of success; negative otherwise
  *
  * A logging context is something like the subscriber identity to which
  * the currently processed message relates, or the BTS through which it
@@ -537,7 +562,12 @@ static void _file_output(struct log_target *target, unsigned int level,
 	fflush(target->tgt_file.out);
 }
 
-/*! \brief Create a new log target skeleton */
+/*! \brief Create a new log target skeleton
+ *  \returns dynamically-allocated log target
+ *  This funcition allocates a \ref log_target and initializes it
+ *  with some default values.  The newly created target is not
+ *  registered yet.
+ */
 struct log_target *log_target_create(void)
 {
 	struct log_target *target;
@@ -574,7 +604,8 @@ struct log_target *log_target_create(void)
 	return target;
 }
 
-/*! \brief Create the STDERR log target */
+/*! \brief Create the STDERR log target
+ *  \returns dynamically-allocated \ref log_target for STDERR */
 struct log_target *log_target_create_stderr(void)
 {
 /* since C89/C99 says stderr is a macro, we can safely do this! */
@@ -639,7 +670,8 @@ struct log_target *log_target_find(int type, const char *fname)
 	return NULL;
 }
 
-/*! \brief Unregister, close and delete a log target */
+/*! \brief Unregister, close and delete a log target
+ *  \param target[in] log target to unregister, close and delete */
 void log_target_destroy(struct log_target *target)
 {
 
@@ -661,7 +693,9 @@ void log_target_destroy(struct log_target *target)
 	talloc_free(target);
 }
 
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open a log file (for log file rotation)
+ *  \param[in] target log target to re-open
+ *  \returns 0 in case of success; negative otherwise */
 int log_target_file_reopen(struct log_target *target)
 {
 	fclose(target->tgt_file.out);
@@ -675,7 +709,8 @@ int log_target_file_reopen(struct log_target *target)
 	return 0;
 }
 
-/*! \brief close and re-open a log file (for log file rotation) */
+/*! \brief close and re-open all log files (for log file rotation)
+ *  \returns 0 in case of success; negative otherwise */
 int log_targets_reopen(void)
 {
 	struct log_target *tar;
@@ -697,6 +732,7 @@ int log_targets_reopen(void)
 
 /*! \brief Generates the logging command string for VTY
  *  \param[in] unused_info Deprecated parameter, no longer used!
+ *  \returns vty command string for use by VTY command node
  */
 const char *log_vty_command_string(const struct log_info *unused_info)
 {
@@ -774,6 +810,7 @@ err:
 
 /*! \brief Generates the logging command description for VTY
  *  \param[in] unused_info Deprecated parameter, no longer used!
+ *  \returns logging command description for use by VTY command node
  */
 const char *log_vty_command_description(const struct log_info *unused_info)
 {
diff --git a/src/macaddr.c b/src/macaddr.c
index a6e1304a..f83e0546 100644
--- a/src/macaddr.c
+++ b/src/macaddr.c
@@ -20,12 +20,24 @@
  *
  */
 
+/*! \addtogroup utils
+ *  @{
+ */
+
+/*! \file loggingrb.c */
+
 #include <stdint.h>
 #include <string.h>
 #include <stdlib.h>
 #include <unistd.h>
 
-
+/*! \brief Parse a MAC address from human-readable notation
+ *  This function parses an ethernet MAC address in the commonly-used
+ *  hex/colon notation (00:00:00:00:00:00) and generates the binary
+ *  representation from it.
+ *  \param[out] out pointer to caller-allocated buffer of 6 bytes
+ *  \param[in] in pointer to input data as string with hex/colon notation
+ */
 int osmo_macaddr_parse(uint8_t *out, const char *in)
 {
 	/* 00:00:00:00:00:00 */
@@ -54,7 +66,11 @@ int osmo_macaddr_parse(uint8_t *out, const char *in)
 #include <net/if_dl.h>
 #include <net/if_types.h>
 
-
+/*! \brief Obtain the MAC address of a given network device
+ *  \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ *  \param[in] dev_name string name of the network device
+ *  \returns 0 in case of success; negative otherwise
+ */
 int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
 {
 	int rc = -1;
@@ -92,6 +108,11 @@ int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
 #include <netinet/in.h>
 #include <netinet/ip.h>
 
+/*! \brief Obtain the MAC address of a given network device
+ *  \param[out] mac_out pointer to caller-allocated buffer of 6 bytes
+ *  \param[in] dev_name string name of the network device
+ *  \returns 0 in case of success; negative otherwise
+ */
 int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
 {
 	int fd, rc;
@@ -114,3 +135,5 @@ int osmo_get_macaddr(uint8_t *mac_out, const char *dev_name)
 	return 0;
 }
 #endif
+
+/*! @} */
diff --git a/src/msgb.c b/src/msgb.c
index 63619130..f09da90d 100644
--- a/src/msgb.c
+++ b/src/msgb.c
@@ -40,6 +40,7 @@ void *tall_msgb_ctx;
 /*! \brief Allocate a new message buffer
  * \param[in] size Length in octets, including headroom
  * \param[in] name Human-readable name to be associated with msgb
+ * \returns dynamically-allocated \ref msgb
  *
  * This function allocates a 'struct msgb' as well as the underlying
  * memory buffer for the actual message data (size specified by \a size)
diff --git a/src/panic.c b/src/panic.c
index 84bab33b..0ce50db2 100644
--- a/src/panic.c
+++ b/src/panic.c
@@ -24,7 +24,9 @@
  *  @{
  */
 
-/*! \file panic.c */
+/*! \file panic.c
+ *  \brief Routines for panic handling
+ */
 
 #include <osmocom/gsm/gsm_utils.h>
 #include <osmocom/core/panic.h>
@@ -58,7 +60,19 @@ static void osmo_panic_default(const char *fmt, va_list args)
 #endif
 
 
-/*! \brief Terminate the current program with a panic */
+/*! \brief Terminate the current program with a panic
+ *
+ * You can call this function in case some severely unexpected situation
+ * is detected and the program is supposed to terminate in a way that
+ * reports the fact that it terminates.
+ *
+ * The application can register a panic handler function using \ref
+ * osmo_set_panic_handler.  If it doesn't, a default panic handler
+ * function is called automatically.
+ *
+ * The default function on most systems will generate a backtrace and
+ * then abort() the process.
+ */
 void osmo_panic(const char *fmt, ...)
 {
 	va_list args;
@@ -74,7 +88,12 @@ void osmo_panic(const char *fmt, ...)
 }
  
 
-/*! \brief Set the panic handler */
+/*! \brief Set the panic handler
+ *  \param[in] h New panic handler function
+ *
+ *  This changes the panic handling function from the currently active
+ *  function to a new call-back function supplied by the caller.
+ */
 void osmo_set_panic_handler(osmo_panic_handler_t h)
 {
 	osmo_panic_handler = h;
diff --git a/src/prim.c b/src/prim.c
index c2e71986..3f41c416 100644
--- a/src/prim.c
+++ b/src/prim.c
@@ -1,6 +1,8 @@
 #include <osmocom/core/utils.h>
 #include <osmocom/core/prim.h>
 
+/*! \brief human-readable string mapping for
+ *  \ref osmo_prim_operation */
 const struct value_string osmo_prim_op_names[5] = {
 	{ PRIM_OP_REQUEST,			"request" },
 	{ PRIM_OP_RESPONSE,			"response" },
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 436deef9..f995f3fd 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -153,7 +153,10 @@ int rate_ctr_init(void *tall_ctx)
 	return 0;
 }
 
-/*! \brief Search for counter group based on group name and index */
+/*! \brief Search for counter group based on group name and index
+ *  \param[in] name Name of the counter group you're looking for
+ *  \param[in] idx Index inside the counter group
+ *  \returns \ref rate_ctr_group or NULL in case of error */
 struct rate_ctr_group *rate_ctr_get_group_by_name_idx(const char *name, const unsigned int idx)
 {
 	struct rate_ctr_group *ctrg;
@@ -170,7 +173,11 @@ 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 */
+/*! \brief Search for counter based on group + name
+ *  \param[in] ctrg pointer to \ref rate_ctr_group
+ *  \param[in] name name of counter inside group
+ *  \returns \ref rate_ctr or NULL in caes of error
+ */
 const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, const char *name)
 {
 	int i;
@@ -189,6 +196,12 @@ const struct rate_ctr *rate_ctr_get_by_name(const struct rate_ctr_group *ctrg, c
 	return NULL;
 }
 
+/*! \brief Iterate over each counter in group and call function
+ *  \param[in] counter group over whose counter to iterate
+ *  \param[in] handle_counter function pointer
+ *  \param[in] data Data to hand transparently to \ref handle_counter
+ *  \returns 0 on success; negative otherwise
+ */
 int rate_ctr_for_each_counter(struct rate_ctr_group *ctrg,
 	rate_ctr_handler_t handle_counter, void *data)
 {
@@ -206,6 +219,11 @@ int rate_ctr_for_each_counter(struct rate_ctr_group *ctrg,
 	return rc;
 }
 
+/*! \brief Iterate over all counter groups
+ *  \param[in] handle_group function pointer of callback function
+ *  \param[in] data Data to hand transparently to \ref handle_group
+ *  \returns 0 on success; negative otherwise
+ */
 int rate_ctr_for_each_group(rate_ctr_group_handler_t handle_group, void *data)
 {
 	struct rate_ctr_group *statg;
@@ -220,5 +238,4 @@ int rate_ctr_for_each_group(rate_ctr_group_handler_t handle_group, void *data)
 	return rc;
 }
 
-
 /*! @} */
diff --git a/src/select.c b/src/select.c
index 02bc2cc3..192cae2f 100644
--- a/src/select.c
+++ b/src/select.c
@@ -47,6 +47,7 @@ static int unregistered_count;
 
 /*! \brief Register a new file descriptor with select loop abstraction
  *  \param[in] fd osmocom file descriptor to be registered
+ *  \returns 0 on success; negative in case of error
  */
 int osmo_fd_register(struct osmo_fd *fd)
 {
@@ -160,6 +161,7 @@ restart:
 
 /*! \brief select main loop integration
  *  \param[in] polling should we pollonly (1) or block on select (0)
+ *  \returns 0 if no fd handled; 1 if fd handled; negative in case of error
  */
 int osmo_select_main(int polling)
 {
@@ -189,7 +191,9 @@ int osmo_select_main(int polling)
 	return osmo_fd_disp_fds(&readset, &writeset, &exceptset);
 }
 
-/*! \brief find an osmo_fd based on the integer fd */
+/*! \brief find an osmo_fd based on the integer fd
+ *  \param[in] fd file descriptor to use as search key
+ *  \returns \ref osmo_fd for \ref fd; NULL in case it doesn't exist */
 struct osmo_fd *osmo_fd_get_by_fd(int fd)
 {
 	struct osmo_fd *ofd;
diff --git a/src/signal.c b/src/signal.c
index 63843849..84025915 100644
--- a/src/signal.c
+++ b/src/signal.c
@@ -46,6 +46,7 @@ struct signal_handler {
  *  \param[in] subsys Subsystem number
  *  \param[in] cbfn Callback function
  *  \param[in] data Data passed through to callback
+ *  \returns 0 on success; negative in case of error
  */
 int osmo_signal_register_handler(unsigned int subsys,
 				 osmo_signal_cbfn *cbfn, void *data)
diff --git a/src/socket.c b/src/socket.c
index 567939b7..7e610bf3 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -57,6 +57,7 @@
  *  \param[in] host remote host name or IP address in string form
  *  \param[in] port remote port number in host byte order
  *  \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ *  \returns socket file descriptor on success; negative on error
  *
  * This function creates a new socket of the designated \a family, \a
  * type and \a proto and optionally binds or connects it, depending on
@@ -153,6 +154,7 @@ int osmo_sock_init(uint16_t family, uint16_t type, uint8_t proto,
 /*! \brief fill \ref osmo_fd for a give sfd
  *  \param[out] ofd file descriptor (will be filled in)
  *  \param[in] sfd socket file descriptor
+ *  \returns socket fd on success; negative on error
  *
  * This function fills the \a ofd structure.
  */
@@ -183,6 +185,7 @@ static inline int osmo_fd_init_ofd(struct osmo_fd *ofd, int sfd)
  *  \param[in] host remote host name or IP address in string form
  *  \param[in] port remote port number in host byte order
  *  \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ *  \returns socket fd on success; negative on error
  *
  * This function creates (and optionall binds/connects) a socket using
  * \ref osmo_sock_init, but also fills the \a ofd structure.
@@ -198,6 +201,7 @@ int osmo_sock_init_ofd(struct osmo_fd *ofd, int family, int type, int proto,
  *  \param[in] type Socket type like SOCK_DGRAM, SOCK_STREAM
  *  \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
  *  \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ *  \returns socket fd on success; negative on error
  *
  * This function creates (and optionall binds/connects) a socket using
  * \ref osmo_sock_init, but also fills the \a ss structure.
@@ -294,6 +298,7 @@ int osmo_sockaddr_is_local(struct sockaddr *addr, unsigned int addrlen)
  *  \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
  *  \param[in] socket_path path to identify the socket
  *  \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ *  \returns socket fd on success; negative on error
  *
  * This function creates a new unix domain socket, \a
  * type and \a proto and optionally binds or connects it, depending on
@@ -365,6 +370,7 @@ err:
  *  \param[in] proto Protocol like IPPROTO_TCP, IPPROTO_UDP
  *  \param[in] socket_path path to identify the socket
  *  \param[in] flags flags like \ref OSMO_SOCK_F_CONNECT
+ *  \returns socket fd on success; negative on error
  *
  * This function creates (and optionall binds/connects) a socket using
  * \ref osmo_sock_unix_init, but also fills the \a ofd structure.
diff --git a/src/timer.c b/src/timer.c
index 21b7015e..0358b89e 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -249,6 +249,8 @@ restart:
 	return work;
 }
 
+/*! \brief Check how many timers we have in the system
+ *  \returns number of \ref osmo_timer_list registered */
 int osmo_timers_check(void)
 {
 	struct rb_node *node;
diff --git a/src/write_queue.c b/src/write_queue.c
index 9a8b05c4..3e488aea 100644
--- a/src/write_queue.c
+++ b/