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