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.

27 files changed, 374 insertions, 186 deletions

diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index e082313a..3218330b 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -13,20 +13,19 @@
 
 /*! \file bits.h
  *  \brief Osmocom bit level support code
+ *
+ *  NOTE on the endianess of pbit_t:
+ *  Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
+ *  Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
  */
 
 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:
-   Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
-   Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
-*/
-
 /*! \brief determine how many bytes we would need for \a num_bits packed bits
  *  \param[in] num_bits Number of packed bits
+ *  \returns number of bytes needed for \a num_bits packed bits
  */
 static inline unsigned int osmo_pbit_bytesize(unsigned int num_bits)
 {
diff --git a/include/osmocom/core/gsmtap.h b/include/osmocom/core/gsmtap.h
index c1ac3edb..c35582e1 100644
--- a/include/osmocom/core/gsmtap.h
+++ b/include/osmocom/core/gsmtap.h
@@ -44,6 +44,7 @@
 #define GSMTAP_TYPE_UMTS_RRC	0x0c
 #define GSMTAP_TYPE_LTE_RRC	0x0d	/* LTE interface */
 #define GSMTAP_TYPE_LTE_MAC	0x0e	/* LTE MAC interface */ 
+#define GSMTAP_TYPE_LTE_MAC_FRAMED	0x0f	/* LTE MAC with context hdr */
 
 /* ====== DO NOT MAKE UNAPPROVED MODIFICATIONS HERE ===== */
 
@@ -235,21 +236,22 @@ enum {
 };
 
 /* ====== DO NOT MAKE UNAPPROVED MODIFICATIONS HERE ===== */
+/*! \brief Structure of the GTMTAP pseudo-header */
 struct gsmtap_hdr {
-	uint8_t version;	/* version, set to 0x01 currently */
-	uint8_t hdr_len;	/* length in number of 32bit words */
-	uint8_t type;		/* see GSMTAP_TYPE_* */
-	uint8_t timeslot;	/* timeslot (0..7 on Um) */
+	uint8_t version;	/*!< version, set to 0x01 currently */
+	uint8_t hdr_len;	/*!< length in number of 32bit words */
+	uint8_t type;		/*!< see GSMTAP_TYPE_* */
+	uint8_t timeslot;	/*!< timeslot (0..7 on Um) */
 
-	uint16_t arfcn;		/* ARFCN (frequency) */
-	int8_t signal_dbm;	/* signal level in dBm */
-	int8_t snr_db;		/* signal/noise ratio in dB */
+	uint16_t arfcn;		/*!< ARFCN (frequency) */
+	int8_t signal_dbm;	/*!< signal level in dBm */
+	int8_t snr_db;		/*!< signal/noise ratio in dB */
 
-	uint32_t frame_number;	/* GSM Frame Number (FN) */
+	uint32_t frame_number;	/*!< GSM Frame Number (FN) */
 
-	uint8_t sub_type;	/* Type of burst/channel, see above */
-	uint8_t antenna_nr;	/* Antenna Number */
-	uint8_t sub_slot;	/* sub-slot within timeslot */
-	uint8_t res;		/* reserved for future use (RFU) */
+	uint8_t sub_type;	/*!< Type of burst/channel, see above */
+	uint8_t antenna_nr;	/*!< Antenna Number */
+	uint8_t sub_slot;	/*!< sub-slot within timeslot */
+	uint8_t res;		/*!< reserved for future use (RFU) */
 
 } __attribute__((packed));
diff --git a/include/osmocom/core/gsmtap_util.h b/include/osmocom/core/gsmtap_util.h
index a5c03e77..2e3d068d 100644
--- a/include/osmocom/core/gsmtap_util.h
+++ b/include/osmocom/core/gsmtap_util.h
@@ -26,7 +26,9 @@ struct gsmtap_inst {
 	struct osmo_fd sink_ofd;/*!< \brief file descriptor */
 };
 
-/*! \brief obtain the file descriptor associated with a gsmtap instance */
+/*! \brief obtain the file descriptor associated with a gsmtap instance
+ *  \param[in] gti GSMTAP instance
+ *  \returns file descriptor of GSMTAP instance */
 static inline int gsmtap_inst_fd(struct gsmtap_inst *gti)
 {
 	return gti->wq.bfd.fd;
diff --git a/include/osmocom/core/linuxlist.h b/include/osmocom/core/linuxlist.h
index 01fd261a..1c833950 100644
--- a/include/osmocom/core/linuxlist.h
+++ b/include/osmocom/core/linuxlist.h
@@ -1,5 +1,21 @@
 #pragma once
 
+/*! \defgroup linuxlist Simple doubly linked list implementation
+ *  @{
+ */
+
+/*!
+ * \file linuxlist.h
+ *
+ * \brief Simple doubly linked list implementation.
+ *
+ * Some of the internal functions ("__xxx") are useful when
+ * manipulating whole llists rather than single entries, as
+ * sometimes we already know the next/prev entries and we can
+ * generate better code by using them directly rather than
+ * using the generic single-entry routines.
+ */
+
 #include <stddef.h>
 
 #ifndef inline
@@ -8,20 +24,18 @@
 
 static inline void prefetch(const void *x) {;}
 
-/**
- * container_of - cast a member of a structure out to the containing structure
- *
- * @ptr:	the pointer to the member.
- * @type:	the type of the container struct this is embedded in.
- * @member:	the name of the member within the struct.
+/*! \brief cast a member of a structure out to the containing structure
  *
+ * \param[in] ptr the pointer to the member.
+ * \param[in] type the type of the container struct this is embedded in.
+ * \param[in] member the name of the member within the struct.
  */
 #define container_of(ptr, type, member) ({			\
         const typeof( ((type *)0)->member ) *__mptr = (ptr);	\
         (type *)( (char *)__mptr - offsetof(type, member) );})
 
 
-/*
+/*!
  * These are non-NULL pointers that will result in page faults
  * under normal circumstances, used to verify that nobody uses
  * non-initialized llist entries.
@@ -29,31 +43,28 @@ static inline void prefetch(const void *x) {;}
 #define LLIST_POISON1  ((void *) 0x00100100)
 #define LLIST_POISON2  ((void *) 0x00200200)
 
-/*
- * Simple doubly linked llist implementation.
- *
- * Some of the internal functions ("__xxx") are useful when
- * manipulating whole llists rather than single entries, as
- * sometimes we already know the next/prev entries and we can
- * generate better code by using them directly rather than
- * using the generic single-entry routines.
- */
-
+/*! \brief (double) linked list header structure */
 struct llist_head {
+	/*! \brief Pointer to next and previous item */
 	struct llist_head *next, *prev;
 };
 
 #define LLIST_HEAD_INIT(name) { &(name), &(name) }
 
+/*! \brief define a statically-initialized \ref llist_head
+ *  \param[in] name Variable name
+ *
+ * This is a helper macro that will define a named variable of type
+ * \ref llist_head and initialize it */
 #define LLIST_HEAD(name) \
 	struct llist_head name = LLIST_HEAD_INIT(name)
 
+/*! \brief initialize a \ref llist_head to point back to self */
 #define INIT_LLIST_HEAD(ptr) do { \
 	(ptr)->next = (ptr); (ptr)->prev = (ptr); \
 } while (0)
 
-/*
- * Insert a new entry between two known consecutive entries. 
+/*! \brief Insert a new entry between two known consecutive entries. 
  *
  * This is only for internal llist manipulation where we know
  * the prev/next entries already!
@@ -68,10 +79,9 @@ static inline void __llist_add(struct llist_head *_new,
 	prev->next = _new;
 }
 
-/**
- * llist_add - add a new entry
- * @new: new entry to be added
- * @head: llist head to add it after
+/*! \brief add a new entry into a linked list (at head)
+ *  \param _new New entry to be added
+ *  \param head \ref llist_head to add it after
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -81,10 +91,9 @@ static inline void llist_add(struct llist_head *_new, struct llist_head *head)
 	__llist_add(_new, head, head->next);
 }
 
-/**
- * llist_add_tail - add a new entry
- * @new: new entry to be added
- * @head: llist head to add it before
+/*! \brief add a new entry into a linked list (at tail)
+ *  \param _new  New entry to be added
+ *  \param head  Head of linked list to whose tail we shall add \a _new
  *
  * Insert a new entry before the specified head.
  * This is useful for implementing queues.
@@ -107,9 +116,9 @@ static inline void __llist_del(struct llist_head * prev, struct llist_head * nex
 	prev->next = next;
 }
 
-/**
- * llist_del - deletes entry from llist.
- * @entry: the element to delete from the llist.
+/*! \brief Delete entry from linked list
+ *  \param entry  The element to delete from the llist
+ *
  * Note: llist_empty on entry does not return true after this, the entry is
  * in an undefined state.
  */
@@ -120,9 +129,8 @@ static inline void llist_del(struct llist_head *entry)
 	entry->prev = (struct llist_head *)LLIST_POISON2;
 }
 
-/**
- * llist_del_init - deletes entry from llist and reinitialize it.
- * @entry: the element to delete from the llist.
+/*! \brief Delete entry from linked list and reinitialize it
+ *  \param entry  The element to delete from the list
  */
 static inline void llist_del_init(struct llist_head *entry)
 {
@@ -130,10 +138,9 @@ static inline void llist_del_init(struct llist_head *entry)
 	INIT_LLIST_HEAD(entry); 
 }
 
-/**
- * llist_move - delete from one llist and add as another's head
- * @llist: the entry to move
- * @head: the head that will precede our entry
+/*! \brief Delete from one llist and add as another's head
+ *  \param llist The entry to move
+ *  \param head	The head that will precede our entry
  */
 static inline void llist_move(struct llist_head *llist, struct llist_head *head)
 {
@@ -141,10 +148,9 @@ static inline void llist_move(struct llist_head *llist, struct llist_head *head)
         llist_add(llist, head);
 }
 
-/**
- * llist_move_tail - delete from one llist and add as another's tail
- * @llist: the entry to move
- * @head: the head that will follow our entry
+/*! \brief Delete from one llist and add as another's tail
+ *  \param llist The entry to move
+ *  \param head The head that will follow our entry
  */
 static inline void llist_move_tail(struct llist_head *llist,
 				  struct llist_head *head)
@@ -153,9 +159,9 @@ static inline void llist_move_tail(struct llist_head *llist,
         llist_add_tail(llist, head);
 }
 
-/**
- * llist_empty - tests whether a llist is empty
- * @head: the llist to test.
+/*! \brief Test whether a linked list is empty
+ *  \param[in] head  The llist to test.
+ *  \returns 1 if the list is empty, 0 otherwise
  */
 static inline int llist_empty(const struct llist_head *head)
 {
@@ -176,10 +182,9 @@ static inline void __llist_splice(struct llist_head *llist,
 	at->prev = last;
 }
 
-/**
- * llist_splice - join two llists
- * @llist: the new llist to add.
- * @head: the place to add it in the first llist.
+/*! \brief Join two llists
+ *  \param llist The new linked list to add
+ *  \param head The place to add \a llist in the other list
  */
 static inline void llist_splice(struct llist_head *llist, struct llist_head *head)
 {
@@ -187,10 +192,9 @@ static inline void llist_splice(struct llist_head *llist, struct llist_head *hea
 		__llist_splice(llist, head);
 }
 
-/**
- * llist_splice_init - join two llists and reinitialise the emptied llist.
- * @llist: the new llist to add.
- * @head: the place to add it in the first llist.
+/*! \brief join two llists and reinitialise the emptied llist.
+ * \param llist The new linked list to add.
+ * \param head  The place to add it in the first llist.
  *
  * The llist at @llist is reinitialised
  */
@@ -203,28 +207,25 @@ static inline void llist_splice_init(struct llist_head *llist,
 	}
 }
 
-/**
- * llist_entry - get the struct for this entry
- * @ptr:	the &struct llist_head pointer.
- * @type:	the type of the struct this is embedded in.
- * @member:	the name of the llist_struct within the struct.
+/*! \brief Get the struct containing this list entry
+ *  \param ptr The \ref llist_head pointer
+ *  \param type The type of the struct this is embedded in
+ *  \param @member The name of the \ref llist_head within the struct
  */
 #define llist_entry(ptr, type, member) \
 	container_of(ptr, type, member)
 
-/**
- * llist_for_each	-	iterate over a llist
- * @pos:	the &struct llist_head to use as a loop counter.
- * @head:	the head for your llist.
+/*! \brief Iterate over a linked list
+ *  \param pos 	The \ref llist_head to use as a loop counter
+ *  \param head The head of the list over which to iterate
  */
 #define llist_for_each(pos, head) \
 	for (pos = (head)->next, prefetch(pos->next); pos != (head); \
         	pos = pos->next, prefetch(pos->next))
 
-/**
- * __llist_for_each	-	iterate over a llist
- * @pos:	the &struct llist_head to use as a loop counter.
- * @head:	the head for your llist.
+/*! \brief Iterate over a llist (no prefetch)
+ *  \param pos 	The \ref llist_head to use as a loop counter
+ *  \param head The head of the list over which to iterate
  *
  * This variant differs from llist_for_each() in that it's the
  * simplest possible llist iteration code, no prefetching is done.
@@ -234,30 +235,27 @@ static inline void llist_splice_init(struct llist_head *llist,
 #define __llist_for_each(pos, head) \
 	for (pos = (head)->next; pos != (head); pos = pos->next)
 
-/**
- * llist_for_each_prev	-	iterate over a llist backwards
- * @pos:	the &struct llist_head to use as a loop counter.
- * @head:	the head for your llist.
+/*! \brief Iterate over a llist backwards
+ *  \param pos 	The \ref llist_head to use as a loop counter
+ *  \param head The head of the list over which to iterate
  */
 #define llist_for_each_prev(pos, head) \
 	for (pos = (head)->prev, prefetch(pos->prev); pos != (head); \
         	pos = pos->prev, prefetch(pos->prev))
-        	
-/**
- * llist_for_each_safe	-	iterate over a llist safe against removal of llist entry
- * @pos:	the &struct llist_head to use as a loop counter.
- * @n:		another &struct llist_head to use as temporary storage
- * @head:	the head for your llist.
+
+/*! \brief Iterate over a list; safe against removal of llist entry
+ *  \param pos 	The \ref llist_head to use as a loop counter
+ *  \param n Another \ref llist_head to use as temporary storage
+ *  \param head The head of the list over which to iterate
  */
 #define llist_for_each_safe(pos, n, head) \
 	for (pos = (head)->next, n = pos->next; pos != (head); \
 		pos = n, n = pos->next)
 
-/**
- * llist_for_each_entry	-	iterate over llist of given type
- * @pos:	the type * to use as a loop counter.
- * @head:	the head for your llist.
- * @member:	the name of the llist_struct within the struct.
+/*! \brief Iterate over llist of given type
+ *  \param pos The 'type *' to use as a loop counter
+ *  \param head The head of the list over which to iterate
+ *  \param member The name of the \ref llist_head within struct \a pos
  */
 #define llist_for_each_entry(pos, head, member)				\
 	for (pos = llist_entry((head)->next, typeof(*pos), member),	\
@@ -266,11 +264,10 @@ static inline void llist_splice_init(struct llist_head *llist,
 	     pos = llist_entry(pos->member.next, typeof(*pos), member),	\
 		     prefetch(pos->member.next))
 
-/**
- * llist_for_each_entry_reverse - iterate backwards over llist of given type.
- * @pos:	the type * to use as a loop counter.
- * @head:	the head for your llist.
- * @member:	the name of the llist_struct within the struct.
+/*! \brief Iterate backwards over llist of given type.
+ *  \param pos The 'type *' to use as a loop counter
+ *  \param head The head of the list over which to iterate
+ *  \param member The name of the \ref llist_head within struct \a pos
  */
 #define llist_for_each_entry_reverse(pos, head, member)			\
 	for (pos = llist_entry((head)->prev, typeof(*pos), member),	\
@@ -279,12 +276,11 @@ static inline void llist_splice_init(struct llist_head *llist,
 	     pos = llist_entry(pos->member.prev, typeof(*pos), member),	\
 		     prefetch(pos->member.prev))
 
-/**
- * llist_for_each_entry_continue -	iterate over llist of given type
- *			continuing after existing point
- * @pos:	the type * to use as a loop counter.
- * @head:	the head for your llist.
- * @member:	the name of the llist_struct within the struct.
+/*! \brief iterate over llist of given type continuing after existing
+ * point
+ *  \param pos The 'type *' to use as a loop counter
+ *  \param head The head of the list over which to iterate
+ *  \param member The name of the \ref llist_head within struct \a pos
  */
 #define llist_for_each_entry_continue(pos, head, member) 		\
 	for (pos = llist_entry(pos->member.next, typeof(*pos), member),	\
@@ -293,13 +289,12 @@ static inline void llist_splice_init(struct llist_head *llist,
 	     pos = llist_entry(pos->member.next, typeof(*pos), member),	\
 		     prefetch(pos->member.next))
 
-/**
- * llist_for_each_entry_safe - iterate over llist of given type, safe against
- *                             removal of non-consecutive(!) llist entries
- * @pos:	the type * to use as a loop counter.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your llist.
- * @member:	the name of the llist_struct within the struct.
+/*! \brief iterate over llist of given type, safe against removal of
+ * non-consecutive(!) llist entries
+ *  \param pos The 'type *' to use as a loop counter
+ *  \param n Another type * to use as temporary storage
+ *  \param head The head of the list over which to iterate
+ *  \param member The name of the \ref llist_head within struct \a pos
  */
 #define llist_for_each_entry_safe(pos, n, head, member)			\
 	for (pos = llist_entry((head)->next, typeof(*pos), member),	\
@@ -355,3 +350,7 @@ static inline void llist_splice_init(struct llist_head *llist,
 #define llist_for_each_continue_rcu(pos, head) \
 	for ((pos) = (pos)->next, prefetch((pos)->next); (pos) != (head); \
         	(pos) = (pos)->next, ({ smp_read_barrier_depends(); 0;}), prefetch((pos)->next))
+
+/*!
+ *  }@
+ */
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index 31934111..4b79c054 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -19,6 +19,11 @@
 #define DEBUG
 
 #ifdef DEBUG
+/*! \brief Log a debug message through the Osmocom logging framework
+ *  \param[in] ss logging subsystem (e.g. \ref DLGLOBAL)
+ *  \param[in] fmt format string
+ *  \param[in] args variable argument list
+ */
 #define DEBUGP(ss, fmt, args...) \
 	do { \
 		if (log_check_level(ss, LOGL_DEBUG)) \
@@ -68,7 +73,7 @@ void logp(int subsys, const char *file, int line, int cont, const char *format,
 
 /*! \brief different log levels */
 #define LOGL_DEBUG	1	/*!< \brief debugging information */
-#define LOGL_INFO	3
+#define LOGL_INFO	3	/*!< \brief general information */
 #define LOGL_NOTICE	5	/*!< \brief abnormal/unexpected condition */
 #define LOGL_ERROR	7	/*!< \brief error condition, requires user action */
 #define LOGL_FATAL	8	/*!< \brief fatal, program aborted */
@@ -76,21 +81,22 @@ void logp(int subsys, const char *file, int line, int cont, const char *format,
 #define LOG_FILTER_ALL	0x0001
 
 /* logging levels defined by the library itself */
-#define DLGLOBAL	-1
-#define DLLAPD		-2
-#define DLINP		-3
-#define DLMUX		-4
-#define DLMI		-5
-#define DLMIB		-6
-#define DLSMS		-7
-#define DLCTRL		-8
-#define DLGTP		-9
-#define DLSTATS		-10
-#define OSMO_NUM_DLIB	10
-
+#define DLGLOBAL	-1	/*!< global logging */
+#define DLLAPD		-2	/*!< LAPD implementation */
+#define DLINP		-3	/*!< (A-bis) Input sub-system */
+#define DLMUX		-4	/*!< Osmocom Multiplex (Osmux) */
+#define DLMI		-5	/*!< ISDN-layer below input sub-system */
+#define DLMIB		-6	/*!< ISDN layer B-channel */
+#define DLSMS		-7	/*!< SMS sub-system */
+#define DLCTRL		-8	/*!< Control Interface */
+#define DLGTP		-9	/*!< GTP (GPRS Tunneling Protocol */
+#define DLSTATS		-10	/*!< Statistics */
+#define OSMO_NUM_DLIB	10	/*!< Number of logging sub-systems in libraries */
+
+/*! Configuration of singgle log category / sub-system */
 struct log_category {
-	uint8_t loglevel;
-	uint8_t enabled;
+	uint8_t loglevel;	/*!< configured log-level */
+	uint8_t enabled;	/*!< is logging enabled? */
 };
 
 /*! \brief Information regarding one logging category */
@@ -136,9 +142,9 @@ struct log_info {
 	/*! \brief total number of user categories (not library) */
 	unsigned int num_cat_user;
 
-	/* \brief filter saving function */
+	/*! \brief filter saving function */
 	log_save_filters *save_fn;
-	/* \brief filter saving function */
+	/*! \brief filter saving function */
 	log_print_filters *print_fn;
 };
 
diff --git a/include/osmocom/core/rate_ctr.h b/include/osmocom/core/rate_ctr.h
index cdde353a..ebaa7a71 100644
--- a/include/osmocom/core/rate_ctr.h
+++ b/include/osmocom/core/rate_ctr.h
@@ -78,10 +78,13 @@ static inline void rate_ctr_group_upd_idx(struct rate_ctr_group *grp, unsigned i
 
 void rate_ctr_group_free(struct rate_ctr_group *grp);
 
-/*! \brief Increment the counter by \a inc */
+/*! \brief Increment the counter by \a inc
+ *  \param ctr \ref rate_ctr to increment
+ *  \param inc quantity to increment \a ctr by */
 void rate_ctr_add(struct rate_ctr *ctr, int inc);
 
-/*! \brief Increment the counter by 1 */
+/*! \brief Increment the counter by 1
+ *  \param ctr \ref rate_ctr to increment */
 static inline void rate_ctr_inc(struct rate_ctr *ctr)
 {
 	rate_ctr_add(ctr, 1);
diff --git a/include/osmocom/core/signal.h b/include/osmocom/core/signal.h
index 6f56496a..5ed4e151 100644
--- a/include/osmocom/core/signal.h
+++ b/include/osmocom/core/signal.h
@@ -7,9 +7,9 @@
  */
 /*! \file signal.h */
 
-/* subsystem signaling numbers: we split the numberspace for applications and
- * libraries: from 0 to UINT_MAX/2 for applications, from UINT_MAX/2 to
- * UINT_MAX for libraries. */
+/*! subsystem signaling numbers: we split the numberspace for
+ * applications and libraries: from 0 to UINT_MAX/2 for applications,
+ * from UINT_MAX/2 to UINT_MAX for libraries. */
 #define OSMO_SIGNAL_SS_APPS		0
 #define OSMO_SIGNAL_SS_RESERVED		2147483648u
 
diff --git a/include/osmocom/core/socket.h b/include/osmocom/core/socket.h
index 1df28c92..6ef0912e 100644
--- a/include/osmocom/core/socket.h
+++ b/include/osmocom/core/socket.h
@@ -14,8 +14,11 @@ struct sockaddr;
 struct osmo_fd;
 
 /* flags for osmo_sock_init. */
+/*! connect the socket to a remote peer */
 #define OSMO_SOCK_F_CONNECT	(1 << 0)
+/*! bind the socket to a local address/port */
 #define OSMO_SOCK_F_BIND	(1 << 1)
+/*! switch socket to non-blocking mode */
 #define OSMO_SOCK_F_NONBLOCK	(1 << 2)
 
 int osmo_sock_init(uint16_t family, uint16_t type, uint8_t proto,
diff --git a/include/osmocom/core/utils.h b/include/osmocom/core/utils.h
index 205fa283..27e1e188 100644
--- a/include/osmocom/core/utils.h
+++ b/include/osmocom/core/utils.h
@@ -53,6 +53,11 @@ do {								\
 	rem -= ret;						\
 } while (0)
 
+/*! Helper macro to terminate when an assertion failes
+ *  \param[in] exp Predicate to verify
+ *  This function will generate a backtrace and terminate the program if
+ *  the predicate evaluates to false (0).
+ */
 #define OSMO_ASSERT(exp)    \
 	if (!(exp)) { \
 		fprintf(stderr, "Assert failed %s %s:%d\n", #exp, __FILE__, __LINE__); \
@@ -60,6 +65,10 @@ do {								\
 		abort(); \
 	}
 
+/*! duplicate a string using talloc and release its prior content (if any)
+ * \param[in] ctx Talloc context to use for allocation
+ * \param[out] dst pointer to string, will be updated with ptr to new string
+ * \param[in] newstr String that will be copieed to newly allocated string */
 static inline void osmo_talloc_replace_string(void *ctx, char **dst, char *newstr)
 {
 	if (*dst)
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/src/write_queue.c
@@ -33,6 +33,7 @@
 /*! \brief Select loop function for write queue handling
  *  \param[in] fd osmocom file descriptor
  *  \param[in] what bit-mask of events that have happened
+ *  \returns 0 on success; negative on error
  *
  * This function is provided so that it can be registered with the
  * select loop abstraction code (\ref osmo_fd::cb).
@@ -99,6 +100,7 @@ void osmo_wqueue_init(struct osmo_wqueue *queue, int max_length)
 /*! \brief Enqueue a new \ref msgb into a write queue
  *  \param[in] queue Write queue to be used
  *  \param[in] data to-be-enqueued message buffer
+ *  \returns 0 on success; negative on error
  */
 int osmo_wqueue_enqueue(struct osmo_wqueue *queue, struct msgb *data)
 {