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.

9 files changed, 162 insertions, 139 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)