diff --git a/include/osmocom/core/msgb.h b/include/osmocom/core/msgb.h
index afb887c..f5dd323 100644
--- a/include/osmocom/core/msgb.h
+++ b/include/osmocom/core/msgb.h
@@ -29,13 +29,7 @@
  *  @{
  */
 
-/*! \file msgb.h
- *  \brief Osmocom message buffers
- * The Osmocom message buffers are modelled after the 'struct skb'
- * inside the Linux kernel network stack.  As they exist in userspace,
- * they are much simplified.  However, terminology such as headroom,
- * tailroom, push/pull/put etc. remains the same.
- */
+/*! \file msgb.h */
 
 #define MSGB_DEBUG
 
diff --git a/src/bits.c b/src/bits.c
index 0c77b27..fe92f93 100644
--- a/src/bits.c
+++ b/src/bits.c
@@ -26,12 +26,11 @@
 
 /*! \addtogroup bits
  *  @{
- */
-
-/*! \file bits.c
  *  \brief Osmocom bit level support code
  */
 
+/*! \file bits.c */
+
 
 /*! \brief convert unpacked bits to packed bits, return length in bytes
  *  \param[out] out output buffer of packed bits
diff --git a/src/bitvec.c b/src/bitvec.c
index c895cff..41e4f64 100644
--- a/src/bitvec.c
+++ b/src/bitvec.c
@@ -24,12 +24,11 @@
 
 /*! \addtogroup bitvec
  *  @{
- */
-
-/*! \file bitvec.c
  *  \brief Osmocom bit vector abstraction
  */
 
+/*! \file bitvec.c */
+
 #include <errno.h>
 #include <stdint.h>
 #include <string.h>
diff --git a/src/conv.c b/src/conv.c
index 79b3a7c..8e97e52 100644
--- a/src/conv.c
+++ b/src/conv.c
@@ -24,11 +24,10 @@
 
 /*! \addtogroup conv
  *  @{
+ *  \brief Osmocom convolutional encoder and decoder
  */
 
-/*! \file conv.c
- * Osmocom convolutional encoder and decoder
- */
+/*! \file conv.c */
 #include "config.h"
 #ifdef HAVE_ALLOCA_H
 #include <alloca.h>
diff --git a/src/crcXXgen.c.tpl b/src/crcXXgen.c.tpl
index 7e45c11..1a69e85 100644
--- a/src/crcXXgen.c.tpl
+++ b/src/crcXXgen.c.tpl
@@ -24,6 +24,7 @@
 
 /*! \addtogroup crcgen
  *  @{
+ *  \brief Osmocom generic CRC routines
  */
 
 /*! \file crcXXgen.c
diff --git a/src/fsm.c b/src/fsm.c
index 5e74482..fbe22d7 100644
--- a/src/fsm.c
+++ b/src/fsm.c
@@ -29,9 +29,6 @@
 
 /*! \addtogroup fsm
  *  @{
- */
-
-/*! \file fsm.c
  *  \brief Finite State Machine abstraction
  *
  *  This is a generic C-language abstraction for implementing finite
@@ -84,9 +81,10 @@
  *
  *  In order to attach private state to the \ref osmo_fsm_inst, it
  *  offers an opaque priv pointer.
- *
  */
 
+/*! \file fsm.c */
+
 LLIST_HEAD(osmo_g_fsms);
 static bool fsm_log_addr = true;
 
diff --git a/src/gb/gprs_ns.c b/src/gb/gprs_ns.c
index 23c0be8..17933ed 100644
--- a/src/gb/gprs_ns.c
+++ b/src/gb/gprs_ns.c
@@ -1648,4 +1648,4 @@
 	DNS = ss;
 }
 
-/*! }@ */
+/*! @} */
diff --git a/src/gsm/a5.c b/src/gsm/a5.c
index dbba0f2..23cbe0c 100644
--- a/src/gsm/a5.c
+++ b/src/gsm/a5.c
@@ -26,13 +26,12 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
-/*! \addtogroup a5
+/*! \addtogroup crypto
  *  @{
+ *  \brief Osmocom GSM/GPRS ciphering algorithm implementation
  */
 
-/*! \file gsm/a5.c
- *  \brief Osmocom GSM A5 ciphering algorithm implementation
- */
+/*! \file gsm/a5.c */
 
 #include <errno.h>
 #include <string.h>
diff --git a/src/gsm/abis_nm.c b/src/gsm/abis_nm.c
index 73759cb..c954902 100644
--- a/src/gsm/abis_nm.c
+++ b/src/gsm/abis_nm.c
@@ -22,6 +22,8 @@
 
 /*! \addtogroup oml
  *  @{
+ * \brief GSM Network Management (OML) messages on the A-bis interface
+ * 3GPP TS 12.21 version 8.0.0 Release 1999 / ETSI TS 100 623 V8.0.0
  */
 
 /*! \file abis_nm.c */
diff --git a/src/gsm/auth_comp128v1.c b/src/gsm/auth_comp128v1.c
index c40027e..3b645d2 100644
--- a/src/gsm/auth_comp128v1.c
+++ b/src/gsm/auth_comp128v1.c
@@ -24,6 +24,10 @@
 #include <osmocom/crypt/auth.h>
 #include <osmocom/gsm/comp128.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int c128v1_gen_vec(struct osmo_auth_vector *vec,
 			  struct osmo_sub_auth_data *aud,
 			  const uint8_t *_rand)
@@ -45,3 +49,5 @@
 {
 	osmo_auth_register(&c128v1_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/auth_comp128v23.c b/src/gsm/auth_comp128v23.c
index 168f886..b0900af 100644
--- a/src/gsm/auth_comp128v23.c
+++ b/src/gsm/auth_comp128v23.c
@@ -27,6 +27,10 @@
 #include <osmocom/crypt/auth.h>
 #include <osmocom/gsm/comp128v23.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int c128v2_gen_vec(struct osmo_auth_vector *vec,
 			  struct osmo_sub_auth_data *aud,
 			  const uint8_t *_rand)
@@ -66,3 +70,5 @@
 	osmo_auth_register(&c128v2_alg);
 	osmo_auth_register(&c128v3_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c
index 9ca5d93..c9e403c 100644
--- a/src/gsm/auth_core.c
+++ b/src/gsm/auth_core.c
@@ -32,10 +32,10 @@
 
 /*! \addtogroup auth
  *  @{
+ *  \brief GSM/GPRS/3G authentication core infrastructure
  */
 
-/* \file auth_core.c
- */
+/* \file auth_core.c */
 
 static LLIST_HEAD(osmo_auths);
 
diff --git a/src/gsm/auth_milenage.c b/src/gsm/auth_milenage.c
index c1331b5..41e538d 100644
--- a/src/gsm/auth_milenage.c
+++ b/src/gsm/auth_milenage.c
@@ -25,6 +25,10 @@
 #include "milenage/common.h"
 #include "milenage/milenage.h"
 
+/*! \addtogroup auth
+ *  @{
+ */
+
 static int milenage_gen_vec(struct osmo_auth_vector *vec,
 			    struct osmo_sub_auth_data *aud,
 			    const uint8_t *_rand)
@@ -160,3 +164,5 @@
 {
 	osmo_auth_register(&milenage_alg);
 }
+
+/*! @} */
diff --git a/src/gsm/comp128.c b/src/gsm/comp128.c
index abb4917..cb3a309 100644
--- a/src/gsm/comp128.c
+++ b/src/gsm/comp128.c
@@ -68,6 +68,14 @@
 #include <string.h>
 #include <stdint.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
+/*! \file comp128.c
+ *  \brief COMP128 v1; common/old GSM Authentication Algorithm (A3/A8)
+ */
+
 /* The compression tables (just copied ...) */
 static const uint8_t table_0[512] = {
  102, 177, 186, 162,   2, 156, 112,  75,  55,  25,   8,  12, 251, 193, 246, 188,
@@ -184,6 +192,11 @@
 		x[(i>>3)+16] |= bits[(i*17) & 127] << (7-(i&7));
 }
 
+/*! \brief Perform COMP128v1 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value */
 void
 comp128v1(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -228,8 +241,16 @@
 	kc[7] = 0;
 }
 
+
+/*! \brief Perform COMP128v1 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value */
 void
 comp128(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
     comp128v1(ki, rand, sres, kc);
 }
+
+/*! @} */
diff --git a/src/gsm/comp128v23.c b/src/gsm/comp128v23.c
index e21b718..bfb4a0e 100644
--- a/src/gsm/comp128v23.c
+++ b/src/gsm/comp128v23.c
@@ -28,6 +28,14 @@
 #include <stdint.h>
 #include <string.h>
 
+/*! \addtogroup auth
+ *  @{
+ */
+
+/*! \file comp128v23.c
+ *  \brief COMP128 v2 / v3; Common Algorithm used for GSM Authentication (A3/A8)
+ */
+
 static const uint8_t table0[256] = {
 	197, 235, 60, 151, 98, 96, 3, 100, 248, 118, 42, 117, 172, 211, 181, 203, 61,
 	126, 156, 87, 149, 224, 55, 132, 186, 63, 238, 255, 85, 83, 152, 33, 160,
@@ -101,6 +109,12 @@
 	}
 }
 
+/*! \brief Perform COMP128v3 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value
+ *  \returns 0 */
 int
 comp128v3(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -147,6 +161,12 @@
 	return 0;
 }
 
+/*! \brief Perform COMP128v2 algorithm
+ *  \param[in] ki Secret Key K(i) of subscriber
+ *  \param[in] rand Random Challenge
+ *  \param[out] sres user-supplied buffer for storing computed SRES value
+ *  \param[out] kc user-supplied buffer for storing computed Kc value
+ *  \returns 0 */
 int
 comp128v2(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc)
 {
@@ -155,3 +175,5 @@
 	kc[6] &= 0xfc;
 	return r;
 }
+
+/*! @} */
diff --git a/src/gsm/gan.c b/src/gsm/gan.c
index 0bcaa17..1d98b38 100644
--- a/src/gsm/gan.c
+++ b/src/gsm/gan.c
@@ -21,6 +21,10 @@
 
 #include <osmocom/gsm/protocol/gsm_44_318.h>
 
+/*! \file gan.c
+ *  \brief Generic Access Network (GAN) / UMA according to TS 44.318
+ */
+
 
 const struct value_string gan_msgt_vals[] = {
 	{ GA_MT_RC_DISCOVERY_REQUEST,	"GA-RC DISCOVERY REQUEST" },
diff --git a/src/gsm/gea.c b/src/gsm/gea.c
index b8f6768..8d026a2 100644
--- a/src/gsm/gea.c
+++ b/src/gsm/gea.c
@@ -30,6 +30,13 @@
 #include <stdint.h>
 #include <string.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
+/*! \file gsm/gea.c */
+
+
 /*! \brief Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0
  *  \param[in,out] out Buffer for gamma for encrypted/decrypted
  *  \param[in] len Length of out, in bytes
@@ -58,3 +65,5 @@
 	osmo_c4(ck, kc);
 	return gea4(out, len, ck, iv, direction);
 }
+
+/*! @} */
diff --git a/src/gsm/gprs_cipher_core.c b/src/gsm/gprs_cipher_core.c
index da6e0a8..a0cf185 100644
--- a/src/gsm/gprs_cipher_core.c
+++ b/src/gsm/gprs_cipher_core.c
@@ -29,6 +29,10 @@
 
 #include <osmocom/crypt/gprs_cipher.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
 static LLIST_HEAD(gprs_ciphers);
 
 static struct gprs_cipher_impl *selected_ciphers[_GPRS_ALGO_NUM];
@@ -125,3 +129,4 @@
 {
 	return iov_i + lfn + oc;
 }
+/*! @} */
diff --git a/src/gsm/gprs_gea.c b/src/gsm/gprs_gea.c
index 8ff1648..836ee68 100644
--- a/src/gsm/gprs_gea.c
+++ b/src/gsm/gprs_gea.c
@@ -27,6 +27,10 @@
 
 #include <stdint.h>
 
+/*! \addtogroup crypto
+ *  @{
+ */
+
 static struct gprs_cipher_impl gea3_impl = {
 	.algo = GPRS_ALGO_GEA3,
 	.name = "GEA3 (libosmogsm built-in)",
@@ -46,3 +50,5 @@
 	gprs_cipher_register(&gea3_impl);
 	gprs_cipher_register(&gea4_impl);
 }
+
+/*! @} */
diff --git a/src/gsm/gprs_rlc.c b/src/gsm/gprs_rlc.c
index a4053ef..d1247be 100644
--- a/src/gsm/gprs_rlc.c
+++ b/src/gsm/gprs_rlc.c
@@ -5,6 +5,10 @@
 #include <osmocom/coding/gsm0503_coding.h>
 #include <osmocom/gprs/protocol/gsm_04_60.h>
 
+/*! \file gsm/gprs_rlc.c
+ *  \brief helper functions for (E)GPRS RLC according to 3GPP TS 44.060
+ */
+
 #define EGPRS_CPS_TYPE1_TBL_SZ		29
 #define EGPRS_CPS_TYPE2_TBL_SZ		8
 #define EGPRS_CPS_TYPE3_TBL_SZ		16
diff --git a/src/gsm/gsm0341.c b/src/gsm/gsm0341.c
index 1c14d3e..2592b54 100644
--- a/src/gsm/gsm0341.c
+++ b/src/gsm/gsm0341.c
@@ -27,6 +27,22 @@
 #include <osmocom/core/talloc.h>
 #include <osmocom/gsm/protocol/gsm_03_41.h>
 
+/*! \addtogroup sms
+ *  @{
+ */
+
+/*! \brief Encode a 3GPP TS 03.41 SMS-CB message
+ *  \param[in] ctx talloc allocation context
+ *  \param[in] geo_scope Geographic Scope
+ *  \param[in] msg_code Message Code
+ *  \param[in] update Is this an update?
+ *  \param[in] msg_id Message ID
+ *  \param[in] dcs Data Coding Scheme
+ *  \param[in] page_total Total number of pages
+ *  \param[in] page_cur Current Page (up to \a page_total)
+ *  \param[in] data Message data (copied 1:1)
+ *  \param[in] len Length of \a data in bytes (up to 88)
+ *  \returns callee-allocated TS 03.41 message with encoded data */
 struct gsm341_ms_message *
 gsm0341_build_msg(void *ctx, uint8_t geo_scope, uint8_t msg_code,
 		  uint8_t update, uint16_t msg_id, uint8_t dcs,
@@ -57,3 +73,5 @@
 
 	return cbmsg;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_smc.c b/src/gsm/gsm0411_smc.c
index 4c08365..03016b9 100644
--- a/src/gsm/gsm0411_smc.c
+++ b/src/gsm/gsm0411_smc.c
@@ -60,6 +60,11 @@
 #include <osmocom/gsm/gsm0411_smc.h>
 #include <osmocom/gsm/protocol/gsm_04_08.h>
 
+/*! \addtogroup sms
+ *  @{
+ *  \brief Point-to-Point (PP) Short Message Service (SMS) as per TS 04.11
+ */
+
 static void cp_timer_expired(void *data);
 
 #define MAX_SMS_RETRY 2
@@ -569,3 +574,5 @@
 
 	return rc;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_smr.c b/src/gsm/gsm0411_smr.c
index eb8aec0..d120f2d 100644
--- a/src/gsm/gsm0411_smr.c
+++ b/src/gsm/gsm0411_smr.c
@@ -62,6 +62,10 @@
 
 #define SMR_LOG_STR "SMR(%" PRIu64 ") "
 
+/*! \addtogroup sms
+ *  @{
+ */
+
 static void rp_timer_expired(void *data);
 
 /* init a new instance */
@@ -484,3 +488,5 @@
 
 	return rc;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0411_utils.c b/src/gsm/gsm0411_utils.c
index b84c9f2..543775c 100644
--- a/src/gsm/gsm0411_utils.c
+++ b/src/gsm/gsm0411_utils.c
@@ -38,16 +38,24 @@
 #include <osmocom/gsm/protocol/gsm_03_40.h>
 #include <osmocom/gsm/protocol/gsm_04_11.h>
 
+/*! \addtogroup sms
+ *  @{
+ */
+
 #define GSM411_ALLOC_SIZE	1024
 #define GSM411_ALLOC_HEADROOM	128
 
+/*! \brief Allocate a message buffer for use as TS 04.11 message
+ *  \returns allocated message buffer */
 struct msgb *gsm411_msgb_alloc(void)
 {
 	return msgb_alloc_headroom(GSM411_ALLOC_SIZE, GSM411_ALLOC_HEADROOM,
 				   "GSM 04.11");
 }
 
-/* Turn int into semi-octet representation: 98 => 0x89 */
+/*! \brief Turn int into semi-octet representation: 98 => 0x89
+ *  \param[in] integer value representing decimal number 0..99
+ *  \returns BSC encoded as nibbles, swapped */
 uint8_t gsm411_bcdify(uint8_t value)
 {
 	uint8_t ret;
@@ -58,7 +66,9 @@
 	return ret;
 }
 
-/* Turn semi-octet representation into int: 0x89 => 98 */
+/*! \brief Turn semi-octet representation into int: 0x89 => 98
+ *  \param[in] value byte containing two BCD nibbles in revere order
+ *  \returns integer representing decoded, re-ordered nibbles */
 uint8_t gsm411_unbcdify(uint8_t value)
 {
 	uint8_t ret;
@@ -73,7 +83,9 @@
 	return ret;
 }
 
-/* Generate 03.40 TP-SCTS */
+/*! \brief Generate 03.40 TP-SCTS
+ *  \param[out] scts Caller-provided buffer to store SCTS (7 octets)
+ *  \param[in] time to encode */
 void gsm340_gen_scts(uint8_t *scts, time_t time)
 {
 	struct tm *tm = gmtime(&time);
@@ -92,7 +104,9 @@
 #endif
 }
 
-/* Decode 03.40 TP-SCTS (into utc/gmt timestamp) */
+/*! \brief Decode 03.40 TP-SCTS (into utc/gmt timestamp)
+ *  \param[in] scts SMS Center Time Stamp
+ *  \return time in UTC time_t format */
 time_t gsm340_scts(uint8_t *scts)
 {
 	struct tm tm;
@@ -190,7 +204,10 @@
 	return minutes;
 }
 
-/* decode validity period. return minutes */
+/*! \brief decode validity period. return minutes
+ *  \param[in] sms_vpf Validity Period Format in 03.40 encoding
+ *  \param[in] sms_vp Validity Period Information Element
+ *  \returns validity period in minutes */
 unsigned long gsm340_validity_period(uint8_t sms_vpf, uint8_t *sms_vp)
 {
 	uint8_t fi; /* functionality indicator */
@@ -228,7 +245,9 @@
 	}
 }
 
-/* determine coding alphabet dependent on GSM 03.38 Section 4 DCS */
+/*! \brief determine coding alphabet dependent on GSM 03.38 Section 4 DCS
+ *  \param[in] dcs Data Coding Scheme in 03.38 encoding
+ *  \returns libosmogsm internal enum \ref sms_alphabet */
 enum sms_alphabet gsm338_get_sms_alphabet(uint8_t dcs)
 {
 	uint8_t cgbits = dcs >> 4;
@@ -266,7 +285,13 @@
 	return alpha;
 }
 
-/* generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 */
+/*! \brief generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 
+ *  \param[out] oa caller-provided output buffer
+ *  \param[in] oa_len caller-specified length of \a oa in bytes
+ *  \param[in] type GSM340_TYPE_*
+ *  \param[in] plan Numbering Plan
+ *  \param[in] number string containing number
+ *  \reurns number of bytes of \a oa that have been used */
 int gsm340_gen_oa(uint8_t *oa, unsigned int oa_len, uint8_t type,
 	uint8_t plan, const char *number)
 {
@@ -296,7 +321,11 @@
 	return len_in_bytes;
 }
 
-/* Prefix msg with a RP header */
+/*! \brief Prefix \ref msgb with a RP header
+ *  \param msg Message Buffer containing message
+ *  \param[in] rp_msg_type RP Message Type
+ *  \param[in] rp_msg_ref RP Message Reference
+ *  \returns 0 */
 int gsm411_push_rp_header(struct msgb *msg, uint8_t rp_msg_type,
 	uint8_t rp_msg_ref)
 {
@@ -312,7 +341,12 @@
 	return 0;
 }
 
-/* Prefix msg with a 04.08/04.11 CP header */
+/*! \brief Prefix \ref msgb with a 04.08/04.11 CP header
+ *  \param msg Message Buffer containing message
+ *  \param[in] proto Protocol
+ *  \param[in] trans Transaction
+ *  \param[in] msg_type Message Type
+ *  \retrns 0 */
 int gsm411_push_cp_header(struct msgb *msg, uint8_t proto, uint8_t trans,
 			     uint8_t msg_type)
 {
@@ -320,3 +354,5 @@
 	gsm0480_l3hdr_push(msg, proto | (trans << 4), msg_type);
 	return 0;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0808.c b/src/gsm/gsm0808.c
index 04c2f01..c96dc77 100644
--- a/src/gsm/gsm0808.c
+++ b/src/gsm/gsm0808.c
@@ -24,9 +24,22 @@
 #include <osmocom/gsm/protocol/gsm_08_08.h>
 #include <osmocom/gsm/gsm48.h>
 
+/*! \addtogroup gsm0808
+ *  @{
+ *  \brief Helper functions regarding the TS 08.08 / 48.008 A interface
+ */
+
 #define BSSMAP_MSG_SIZE 512
 #define BSSMAP_MSG_HEADROOM 128
 
+/*! \brief Create "Complete L3 Info" for AoIP
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \param[in] scl Speech Codec List
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc,
 					uint16_t cc, int lac, uint16_t _ci,
 					const struct gsm0808_speech_codec_list
@@ -68,12 +81,21 @@
 	return msg;
 }
 
+/*! \brief Create "Complete L3 Info" for A
+ *  \param[in] msg_l3 msgb containing Layer 3 Message
+ *  \param[in] nc Mobile Network Code
+ *  \param[in] cc Mobile Country Code
+ *  \param[in] lac Location Area Code
+ *  \param[in] _ci Cell Identity
+ *  \returns callee-allocated msgb with Complete L3 Info message */
 struct msgb *gsm0808_create_layer3(struct msgb *msg_l3, uint16_t nc,
 				   uint16_t cc, int lac, uint16_t _ci)
 {
 	return gsm0808_create_layer3_aoip(msg_l3, nc, cc, lac, _ci, NULL);
 }
 
+/*! \brief Create BSSMAP RESET message
+ *  \returns callee-allocated msgb with BSSMAP Reset message */
 struct msgb *gsm0808_create_reset(void)
 {
 	uint8_t cause = GSM0808_CAUSE_EQUIPMENT_FAILURE;
@@ -89,6 +111,8 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP RESET ACK message
+ *  \returns callee-allocated msgb with BSSMAP Reset ACK message */
 struct msgb *gsm0808_create_reset_ack(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -102,6 +126,8 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Complete message
+ *  \returns callee-allocated msgb with BSSMAP Clear Complete message */
 struct msgb *gsm0808_create_clear_complete(void)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -116,6 +142,9 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Clear Command message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Command message */
 struct msgb *gsm0808_create_clear_command(uint8_t reason)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -130,6 +159,10 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Command message
+ *  \param[in] ei Mandatory Encryption Information
+ *  \param[in] cipher_response_mode optional 1-byte Cipher Response Mode
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Command message */
 struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei,
 				   const uint8_t *cipher_response_mode)
 {
@@ -163,6 +196,10 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Complete message
+ *  \param[in] layer3 L3 Message to be included
+ *  \param[in] alg_id Chosen Encrpytion Algorithm
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Complete message */
 struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -188,6 +225,9 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Cipher Mode Reject message
+ *  \param[in] reason TS 08.08 cause value
+ *  \returns callee-allocated msgb with BSSMAP Cipher Mode Reject message */
 struct msgb *gsm0808_create_cipher_reject(uint8_t cause)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -202,6 +242,12 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Classmark Update message
+ *  \param[in] cm2 Classmark 2
+ *  \param[in] cm2_len length (in octets) of \a cm2
+ *  \param[in] cm3 Classmark 3
+ *  \param[in] cm3_len length (in octets) of \a cm3
+ *  \returns callee-allocated msgb with BSSMAP Classmark Update message */
 struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len,
 					     const uint8_t *cm3, uint8_t cm3_len)
 {
@@ -221,6 +267,9 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP SAPI N Reject message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP SAPI N Reject message */
 struct msgb *gsm0808_create_sapi_reject(uint8_t link_id)
 {
 	struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM,
@@ -237,6 +286,13 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Request message
+ *  \param[in] ct Channel Type
+ *  \param[in] cic Circuit Identity Code (Classic A only)
+ *  \param[in] ss Socket Address of MSC-side RTP socket (AoIP only)
+ *  \param[in] scl Speech Codec List (AoIP only)
+ *  \param[in] ci Call Identifier (Optional, LCLS)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Request message */
 struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct,
 				const uint16_t *cic,
 				const struct sockaddr_storage *ss,
@@ -293,6 +349,15 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \param[in] ss Socket Address of BSS-side RTP socket
+ *  \param[in] sc Speech Codec (current)
+ *  \param[in] scl Speech Codec List (permitted)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel,
 				      uint8_t encr_alg_id, uint8_t speech_mode,
 				      const struct sockaddr_storage *ss,
@@ -342,6 +407,12 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Completed message
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] chosen_channel Chosen Channel
+ *  \param[in] encr_alg_id Encryption Algorithm ID
+ *  \param[in] speech_mode Speech Mode
+ *  \returns callee-allocated msgb with BSSMAP Assignment Complete message */
 struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause,
 						 uint8_t chosen_channel,
 						 uint8_t encr_alg_id,
@@ -351,6 +422,11 @@
 					speech_mode, NULL, NULL, NULL);
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \param[in] scl Optional Speech Cdec List (AoIP)
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause,
 				     const struct gsm0808_speech_codec_list
 				     *scl)
@@ -380,12 +456,19 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP Assignment Failure message
+ *  \param[in] cause BSSMAP Cause value
+ *  \param[in] rr_cause GSM 04.08 RR Cause value
+ *  \returns callee-allocated msgb with BSSMAP Assignment Failure message */
 struct msgb *gsm0808_create_assignment_failure(uint8_t cause,
 					       uint8_t *rr_cause)
 {
 	return gsm0808_create_ass_fail(cause, rr_cause, NULL);
 }
 
+/*! \brief Create BSSMAP Clear Request message
+ *  \param[in] cause BSSMAP Cause value
+ *  \returns callee-allocated msgb with BSSMAP Clear Request message */
 struct msgb *gsm0808_create_clear_rqst(uint8_t cause)
 {
 	struct msgb *msg;
@@ -402,6 +485,12 @@
 	return msg;
 }
 
+/*! \brief Create BSSMAP PAGING message
+ *  \param[in] imsi Mandatory paged IMSI in string representation
+ *  \param[in] tmsi Optional paged TMSI
+ *  \param[in] cil Cell Identity List (where to page)
+ *  \param[in] chan_needed Channel Type needed
+ *  \returns callee-allocated msgb with BSSMAP PAGING message */
 struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi,
 				   const struct gsm0808_cell_id_list *cil,
 				   const uint8_t *chan_needed)
@@ -454,6 +543,9 @@
 	return msg;
 }
 
+/*! \brief Prepend a DTAP header to given Message Buffer
+ *  \param[in] msgb Message Buffer
+ *  \param[in] link_id Link Identifier */
 void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id)
 {
 	uint8_t *hh = msgb_push(msg, 3);
@@ -462,6 +554,10 @@
 	hh[2] = msg->len - 3;
 }
 
+/*! \brief Create BSSMAP DTAP message
+ *  \param[in] msg_l3 Messge Buffer containing Layer3 message
+ *  \param[in] link_id Link Identifier
+ *  \returns callee-allocated msgb with BSSMAP DTAP message */
 struct msgb *gsm0808_create_dtap(struct msgb *msg_l3, uint8_t link_id)
 {
 	struct dtap_header *header;
@@ -722,6 +818,7 @@
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSMAP Message Type */
 const char *gsm0808_bssmap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_msgt_names, msg_type);
@@ -733,7 +830,10 @@
 	{ 0, NULL }
 };
 
+/*! \brief Return string name of BSSAP Message Type */
 const char *gsm0808_bssap_name(uint8_t msg_type)
 {
 	return get_value_string(gsm0808_bssap_names, msg_type);
 }
+
+/*! @} */
diff --git a/src/gsm/gsm0808_utils.c b/src/gsm/gsm0808_utils.c
index ff97b2d..bdd02e5 100644
--- a/src/gsm/gsm0808_utils.c
+++ b/src/gsm/gsm0808_utils.c
@@ -39,7 +39,15 @@
 
 #include <sys/socket.h>
 #include <netinet/in.h>
-/* Encode AoIP transport address element */
+
+/*! \addtogroup gsm0808
+ *  @{
+ */
+
+/*! \brief Encode TS 08.08 AoIP transport address IE
+ *  \param[out] msg Message Buffer to which to append IE
+ *  \param[in] ss Socket Address to be used in IE
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_aoip_trasp_addr(struct msgb *msg,
 				    const struct sockaddr_storage *ss)
 {
@@ -80,7 +88,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode AoIP transport address element */
+/*! \brief Decode TS 08.08 AoIP transport address IE
+ *  \param[out] ss Caller-provided memory where decoded socket addr is stored
+ *  \param[in] elem pointer to IE value
+ *  \param[in] len length of \a elem in bytes
+ *  \returns number of bytes parsed */
 int gsm0808_dec_aoip_trasp_addr(struct sockaddr_storage *ss,
 				const uint8_t *elem, uint8_t len)
 {
@@ -168,7 +180,10 @@
 	return (uint8_t) (msg->tail - old_tail);
 }
 
-/* Encode Speech Codec element */
+/*! \brief Encode TS 08.08 Speech Codec IE
+ *  \param[out] msg Message Buffer to which IE will be appended
+ *  \param[in] sc Speech Codec to be encoded into IE
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_speech_codec(struct msgb *msg,
 				 const struct gsm0808_speech_codec *sc)
 {
@@ -188,7 +203,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode Speech Codec element */
+/*! \brief Decode TS 08.08 Speech Codec IE
+ *  \param[out] sc Caller-allocated memory for Speech Codec
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_speech_codec(struct gsm0808_speech_codec *sc,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -244,7 +263,10 @@
 	return (int)(elem - old_elem);
 }
 
-/* Encode Speech Codec list */
+/*! \brief Encode TS 08.08 Speech Codec list
+ *  \param[out] msg  Message Buffer to which IE is to be appended
+ *  \param[in] scl Speech Codec List to be encoded into IE
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_speech_codec_list(struct msgb *msg,
 				      const struct gsm0808_speech_codec_list *scl)
 {
@@ -275,7 +297,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode Speech Codec list */
+/*! \brief Decode TS 08.08 Speech Codec list IE
+ *  \param[out] scl Caller-provided memory to store codec list
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_speech_codec_list(struct gsm0808_speech_codec_list *scl,
 				  const uint8_t *elem, uint8_t len)
 {
@@ -315,7 +341,10 @@
 	return (int)(elem - old_elem);
 }
 
-/* Encode Channel Type element */
+/*! \brief Encode TS 08.08 Channel Type IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] ct Channel Type to be encoded
+ *  \returns number of bytes added to \a msg */
 uint8_t gsm0808_enc_channel_type(struct msgb *msg,
 				 const struct gsm0808_channel_type *ct)
 {
@@ -353,7 +382,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode Channel Type element */
+/*! \brief Decode TS 08.08 Channel Type IE
+ *  \param[out] ct Caller-provided memory to store channel type
+ *  \param[in] elem IE Value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_channel_type(struct gsm0808_channel_type *ct,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -386,7 +419,10 @@
 	return (int)(elem - old_elem);
 }
 
-/* Encode Encryption Information element */
+/*! \brief Encode TS 08.08 Encryption Information IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] ei Encryption Information to be encoded
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_encrypt_info(struct msgb *msg,
 				 const struct gsm0808_encrypt_info *ei)
 {
@@ -421,7 +457,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode Encryption Information element */
+/*! \brief Decode TS 08.08 Encryption Information IE
+ *  \param[out] ei Caller-provided memory to store encryption information
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_encrypt_info(struct gsm0808_encrypt_info *ei,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -456,7 +496,10 @@
 	return (int)(elem - old_elem);
 }
 
-/* Encode Cell Identifier List element */
+/*! \brief Encode TS 08.08 Cell Identifier List IE
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] cil Cell ID List to be encoded
+ *  \returns number of bytes appended to \a msg */
 uint8_t gsm0808_enc_cell_id_list(struct msgb *msg,
 				 const struct gsm0808_cell_id_list *cil)
 {
@@ -492,7 +535,11 @@
 	return *tlv_len + 2;
 }
 
-/* Decode Cell Identifier List element */
+/*! \brief Decode Cell Identifier List IE
+ *  \param[out] cil Caller-provided memory to store Cell ID list
+ *  \param[in] elem IE value to be decoded
+ *  \param[in] len Length of \a elem in bytes
+ *  \returns number of bytes parsed; negative on error */
 int gsm0808_dec_cell_id_list(struct gsm0808_cell_id_list *cil,
 			     const uint8_t *elem, uint8_t len)
 {
@@ -533,3 +580,5 @@
 	cil->id_list_len = item_count;
 	return (int)(elem - old_elem);
 }
+
+/*! @} */
diff --git a/src/gsm/gsm48.c b/src/gsm/gsm48.c
index 543c9c0..1b25538 100644
--- a/src/gsm/gsm48.c
+++ b/src/gsm/gsm48.c
@@ -39,6 +39,12 @@
 #include <osmocom/gsm/protocol/gsm_08_58.h>
 #include <osmocom/gsm/protocol/gsm_04_08_gprs.h>
 
+/*! \addtogroup gsm0408
+ *  @{
+ *  \brief GSM Mobile Radion Interface L3 messages / TS 04.08
+ */
+
+/*! \brief TLV parser definitions for TS 04.08 CC */
 const struct tlv_definition gsm48_att_tlvdef = {
 	.def = {
 		[GSM48_IE_MOBILE_ID]	= { TLV_TYPE_TLV },
@@ -80,7 +86,7 @@
 	},
 };
 
-/* RR elements */
+/*! \brief TLV parser definitions for TS 04.08 RR */
 const struct tlv_definition gsm48_rr_att_tlvdef = {
 	.def = {
 		/* NOTE: Don't add IE 17 = MOBILE_ID here, it already used. */
@@ -125,7 +131,7 @@
 	},
 };
 
-/* MM elements */
+/*! \brief TLV parser definitions for TS 04.08 MM */
 const struct tlv_definition gsm48_mm_att_tlvdef = {
 	.def = {
 		[GSM48_IE_MOBILE_ID]		= { TLV_TYPE_TLV },
@@ -164,6 +170,7 @@
 	{ 0,					NULL },
 };
 
+/*! \brief return string representation of RR Cause value */
 const char *rr_cause_name(uint8_t cause)
 {
 	return get_value_string(rr_cause_names, cause);
@@ -205,6 +212,7 @@
 	"illegal state 31",
 };
 
+/*! \brief return string representation of CC State */
 const char *gsm48_cc_state_name(uint8_t state)
 {
 	if (state < ARRAY_SIZE(cc_state_names))
@@ -252,6 +260,7 @@
 	{ 0,				NULL }
 };
 
+/*! \brief return string representation of CC Message Type */
 const char *gsm48_cc_msg_name(uint8_t msgtype)
 {
 	return get_value_string(cc_msg_names, msgtype);
@@ -359,6 +368,7 @@
 	{ 0,				NULL }
 };
 
+/*! \brief return string representation of RR Message Type */
 const char *gsm48_rr_msg_name(uint8_t msgtype)
 {
 	return get_value_string(rr_msg_names, msgtype);
@@ -398,6 +408,7 @@
 	{ 0,			NULL }
 };
 
+/*! \brief return string representation of Mobile Identity Type */
 const char *gsm48_mi_type_name(uint8_t mi)
 {
 	return get_value_string(mi_type_names, mi);
@@ -437,7 +448,12 @@
 	}
 }
 
-/* Convert given mcc and mnc to BCD and write to *bcd_dst, which must be an
+/* \brief Convert MCC + MNC to BCD representation
+ * \param[out] bcd_dst caller-allocated memory for output
+ * \param[in] mcc Mobile Country Code
+ * \param[in] mnc Mobile Network Code
+ *
+ * Convert given mcc and mnc to BCD and write to *bcd_dst, which must be an
  * allocated buffer of (at least) 3 bytes length. */
 void gsm48_mcc_mnc_to_bcd(uint8_t *bcd_dst, uint16_t mcc, uint16_t mnc)
 {
@@ -477,6 +493,11 @@
 	}
 }
 
+/*! \brief Encode TS 04.08 Location Area Identifier
+ *  \param[out] caller-provided memory for output
+ *  \param[in] mcc Mobile Country Code
+ *  \param[in] mnc Mobile Network Code
+ *  \param[in] lac Location Area Code */
 void gsm48_generate_lai(struct gsm48_loc_area_id *lai48, uint16_t mcc,
 			uint16_t mnc, uint16_t lac)
 {
@@ -484,7 +505,14 @@
 	lai48->lac = osmo_htons(lac);
 }
 
-/* Attention: this function returns true integers, not hex! */
+/*! \brief Decode TS 04.08 Location Area Identifier
+ *  \param[in] Location Area Identifier (encoded)
+ *  \param[out] mcc Mobile Country Code
+ *  \param[out] mnc Mobile Network Code
+ *  \param[out] lac Location Area Code
+ *  \returns 0
+ *
+ * Attention: this function returns true integers, not hex! */
 int gsm48_decode_lai(struct gsm48_loc_area_id *lai, uint16_t *mcc,
 		     uint16_t *mnc, uint16_t *lac)
 {
@@ -537,6 +565,10 @@
 	}
 }
 
+/*! \brief Generate TS 04.08 Mobile ID from TMSI
+ *  \param[out] buf Caller-provided output buffer (7 bytes)
+ *  \param[in] tmsi TMSI to be encoded
+ *  \returns number of byes encoded (always 7) */
 int gsm48_generate_mid_from_tmsi(uint8_t *buf, uint32_t tmsi)
 {
 	uint32_t tmsi_be = osmo_htonl(tmsi);
@@ -549,6 +581,10 @@
 	return 7;
 }
 
+/*! \brief Generate TS 04.08 Mobile ID from IMSI
+ *  \param[out] buf Caller-provided output buffer
+ *  \param[in] imsi IMSI to be encoded
+ *  \returns number of bytes used in \a buf */
 int gsm48_generate_mid_from_imsi(uint8_t *buf, const char *imsi)
 {
 	unsigned int length = strlen(imsi), i, off = 0;
@@ -578,7 +614,12 @@
 	return 2 + buf[1];
 }
 
-/* Convert Mobile Identity (10.5.1.4) to string */
+/*! \brief Convert TS 04.08 Mobile Identity (10.5.1.4) to string
+ *  \param[out] string Caller-provided buffer for output
+ *  \param[in] str_len Length of \a string in bytes
+ *  \param[in] mi Mobile Identity to be stringified
+ *  \param[in] mi_len Length of \a mi in bytes
+ *  \returns length of string written to \a string */
 int gsm48_mi_to_string(char *string, const int str_len, const uint8_t *mi,
 		       const int mi_len)
 {
@@ -621,6 +662,9 @@
 	return str_cur - string;
 }
 
+/*! \brief Parse TS 04.08 Routing Area Identifier
+ *  \param[out] Caller-provided memory for decoded RA ID
+ *  \param[in] buf Input buffer pointing to RAI IE value */
 void gsm48_parse_ra(struct gprs_ra_id *raid, const uint8_t *buf)
 {
 	raid->mcc = (buf[0] & 0xf) * 100;
@@ -642,6 +686,10 @@
 	raid->rac = buf[5];
 }
 
+/*! \brief Encode a TS 04.08 Routing Area Identifier
+ *  \param[out] buf Caller-provided output buffer of 6 bytes
+ *  \param[in] raid Routing Area ID to be encoded
+ *  \returns number of bytes used in \a buf */
 int gsm48_construct_ra(uint8_t *buf, const struct gprs_ra_id *raid)
 {
 	uint16_t mcc = raid->mcc;
@@ -669,7 +717,13 @@
 	return 6;
 }
 
-/* From Table 10.5.33 of GSM 04.08 */
+/*! \brief Determine number of paging sub-channels
+ *  \param[in] chan_desc Control Channel Description
+ *  \returns number of paging sub-channels
+ *
+ *  Uses From Table 10.5.33 of GSM 04.08 to determine the number of
+ *  paging sub-channels in the given control channel configuration
+ */
 int gsm48_number_of_paging_subchannels(struct gsm48_control_channel_descr *chan_desc)
 {
 	unsigned int n_pag_blocks = gsm0502_get_n_pag_blocks(chan_desc);
@@ -680,6 +734,7 @@
 		return n_pag_blocks * (chan_desc->bs_pa_mfrms + 2);
 }
 
+/*! \brief TS 04.08 Protocol Descriptor names */
 const struct value_string gsm48_pdisc_names[] = {
 	OSMO_VALUE_STRING(GSM48_PDISC_GROUP_CC),
 	OSMO_VALUE_STRING(GSM48_PDISC_BCAST_CC),
@@ -699,6 +754,7 @@
 	{ 0, NULL }
 };
 
+/*! \brief TS 04.08 RR Message Type names */
 const struct value_string gsm48_rr_msgtype_names[] = {
 	OSMO_VALUE_STRING(GSM48_MT_RR_INIT_REQ),
 	OSMO_VALUE_STRING(GSM48_MT_RR_ADD_ASS),
@@ -791,6 +847,7 @@
 	{ 0, NULL }
 };
 
+/*! \brief TS 04.08 MM Message Type names */
 const struct value_string gsm48_mm_msgtype_names[] = {
 	OSMO_VALUE_STRING(GSM48_MT_MM_IMSI_DETACH_IND),
 	OSMO_VALUE_STRING(GSM48_MT_MM_LOC_UPD_ACCEPT),
@@ -820,6 +877,7 @@
 	{ 0, NULL }
 };
 
+/*! \brief TS 04.08 CC Message Type names */
 const struct value_string gsm48_cc_msgtype_names[] = {
 	OSMO_VALUE_STRING(GSM48_MT_CC_ALERTING),
 	OSMO_VALUE_STRING(GSM48_MT_CC_CALL_CONF),
@@ -862,12 +920,12 @@
 	{ 0, NULL }
 };
 
-/*! /brief Compose a string naming the message type for given protocol.
+/*! \brief Compose a string naming the message type for given protocol.
  * If the message type string is known, return the message type name, otherwise
  * return "<protocol discriminator name>:<message type in hex>".
- * /param pdisc[in]  protocol discriminator like GSM48_PDISC_MM
- * /param msg_type[in]  message type like GSM48_MT_MM_LOC_UPD_REQUEST
- * /returns statically allocated string or string constant.
+ * \param[in] pdisc protocol discriminator like GSM48_PDISC_MM
+ * \param[in] msg_type message type like GSM48_MT_MM_LOC_UPD_REQUEST
+ * \returns statically allocated string or string constant.
  */
 const char *gsm48_pdisc_msgtype_name(uint8_t pdisc, uint8_t msg_type)
 {
@@ -896,3 +954,5 @@
 		 gsm48_pdisc_name(pdisc), msg_type);
 	return namebuf;
 }
+
+/*! @} */
diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c
index 2cc0645..20d0075 100644
--- a/src/gsm/gsm48_ie.c
+++ b/src/gsm/gsm48_ie.c
@@ -34,12 +34,20 @@
 #include <osmocom/gsm/protocol/gsm_04_08.h>
 #include <osmocom/gsm/gsm48_ie.h>
 
+/*! \addtogroup gsm0408
+ *  @{
+ */
+
 static const char bcd_num_digits[] = {
 	'0', '1', '2', '3', '4', '5', '6', '7',
 	'8', '9', '*', '#', 'a', 'b', 'c', '\0'
 };
 
-/* decode a 'called/calling/connect party BCD number' as in 10.5.4.7 */
+/*! \brief decode a 'called/calling/connect party BCD number' as in 10.5.4.7
+ *  \param[out] Caller-provided output buffer
+ *  \param[in] bcd_lv Length-Value portion of to-be-decoded IE
+ *  \param[in] h_len Length of an optional heder between L and V portion
+ *  \returns - in case of success; negative on error */
 int gsm48_decode_bcd_number(char *output, int output_len,
 			    const uint8_t *bcd_lv, int h_len)
 {
@@ -65,7 +73,7 @@
 	return 0;
 }
 
-/* convert a single ASCII character to call-control BCD */
+/*! \brief convert a single ASCII character to call-control BCD */
 static int asc_to_bcd(const char asc)
 {
 	int i;
@@ -77,7 +85,12 @@
 	return -EINVAL;
 }
 
-/* convert a ASCII phone number to 'called/calling/connect party BCD number' */
+/*! \brief convert a ASCII phone number to 'called/calling/connect party BCD number'
+ *  \param[out] bcd_lv Caller-provided output buffer
+ *  \param[in] max_len Maximum Length of \a bcd_lv
+ *  \param[in] h_len Length of an optional heder between L and V portion
+ *  \param[in] input phone number as 0-terminated ASCII
+ *  \returns number of bytes used in \a bcd_lv */
 int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len,
 		      int h_len, const char *input)
 {
@@ -110,7 +123,10 @@
 	return (bcd_cur - bcd_lv);
 }
 
-/* TS 04.08 10.5.4.5: decode 'bearer capability' */
+/*! \brief Decode TS 04.08 Bearer Capability IE (10.5.4.5)
+ *  \param[out] Caller-provided memory for decoded output
+ *  \[aram[in] LV portion of TS 04.08 Bearer Capability
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap,
 			     const uint8_t *lv)
 {
@@ -219,7 +235,11 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5: encode 'bearer capability' */
+/*! \brief Encode TS 04.08 Bearer Capability IE (10.5.4.5)
+ *  \param[out] msg Message Buffer to which IE is to be appended
+ *  \param[in] lv_only Write only LV portion (1) or TLV (0)
+ *  \param[in] bcap Decoded Bearer Capability to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only,
 			     const struct gsm_mncc_bearer_cap *bcap)
 {
@@ -274,7 +294,10 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5a: decode 'call control cap' */
+/*! \brief Decode TS 04.08 Call Control Capabilities IE (10.5.4.5a)
+ *  \param[out] Caller-provided memory for decoded CC capabilities
+ *  \param[in] lv Length-Value of IE
+ *  \retursns 0 on success; negative on error */
 int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv)
 {
 	uint8_t in_len = lv[0];
@@ -289,7 +312,10 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.5a: encode 'call control cap' */
+/*! \brief Encodoe TS 04.08 Call Control Capabilities (10.5.4.5a)
+ *  \param[out] msg Message Buffer to which to append IE (as TLV)
+ *  \param[in] ccap Decoded CC Capabilities to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_cccap(struct msgb *msg,
 			const struct gsm_mncc_cccap *ccap)
 {
@@ -307,7 +333,10 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.7: decode 'called party BCD number' */
+/*! \brief Decode TS 04.08 Called Party BCD Number IE (10.5.4.7)
+ *  \param[out] called Caller-provided memory for decoded number
+ *  \param[in] lv Length-Value portion of IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_called(struct gsm_mncc_number *called,
 			 const uint8_t *lv)
 {
@@ -326,7 +355,10 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.7: encode 'called party BCD number' */
+/*! \brief Encode TS 04.08 Called Party IE (10.5.4.7)
+ *  \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ *  \param[in] called MNCC Number to encode/append
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_called(struct msgb *msg,
 			 const struct gsm_mncc_number *called)
 {
@@ -348,7 +380,10 @@
 	return 0;
 }
 
-/* decode callerid of various IEs */
+/*! \brief Decode TS 04.08 Caller ID
+ *  \param[out] called Caller-provided memory for decoded number
+ *  \param[in] lv Length-Value portion of IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_callerid(struct gsm_mncc_number *callerid,
 			 const uint8_t *lv)
 {
@@ -375,7 +410,12 @@
 	return 0;
 }
 
-/* encode callerid of various IEs */
+/*! \brief Encode TS 04.08 Caller ID IE
+ *  \param[out] msg Mesage Buffer to which to append IE (as TLV)
+ *  \param[in] ie IE Identifier (tag)
+ *  \param[in] max_len maximum generated output in bytes
+ *  \param[in] callerid MNCC Number to encode/append
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len,
 			   const struct gsm_mncc_number *callerid)
 {
@@ -406,7 +446,10 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.11: decode 'cause' */
+/*! \brief Decode TS 04.08 Cause IE (10.5.4.11)
+ *  \param[out] cause Caller-provided memory for output
+ *  \param[in] lv LV portion of Cause IE
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_cause(struct gsm_mncc_cause *cause,
 			const uint8_t *lv)
 {
@@ -449,7 +492,11 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.11: encode 'cause' */
+/*! \brief Encode TS 04.08 Cause IE (10.5.4.11)
+ *  \param[out] msg Message Buffer to which to append IE
+ *  \param[in] lv_only Encode as LV (1) or TLV (0)
+ *  \param[in] cause Cause value to be encoded
+ *  \returns 0 on success; negative on error */
 int gsm48_encode_cause(struct msgb *msg, int lv_only,
 			const struct gsm_mncc_cause *cause)
 {
@@ -489,49 +536,49 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.9: decode 'calling number' */
+/*! \brief Decode TS 04.08 Calling Number IE (10.5.4.9) */
 int gsm48_decode_calling(struct gsm_mncc_number *calling,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(calling, lv);
 }
 
-/* TS 04.08 10.5.4.9: encode 'calling number' */
+/*! \brief Encode TS 04.08 Calling Number IE (10.5.4.9) */
 int gsm48_encode_calling(struct msgb *msg, 
 			  const struct gsm_mncc_number *calling)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_CALLING_BCD, 14, calling);
 }
 
-/* TS 04.08 10.5.4.13: decode 'connected number' */
+/*! \brief Decode TS 04.08 Connected Number IE (10.5.4.13) */
 int gsm48_decode_connected(struct gsm_mncc_number *connected,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(connected, lv);
 }
 
-/* TS 04.08 10.5.4.13: encode 'connected number' */
+/*! \brief Encode TS 04.08 Connected Number IE (10.5.4.13) */
 int gsm48_encode_connected(struct msgb *msg,
 			    const struct gsm_mncc_number *connected)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_CONN_BCD, 14, connected);
 }
 
-/* TS 04.08 10.5.4.21b: decode 'redirecting number' */
+/*! \brief Decode TS 04.08 Redirecting Number IE (10.5.4.21b) */
 int gsm48_decode_redirecting(struct gsm_mncc_number *redirecting,
 			 const uint8_t *lv)
 {
 	return gsm48_decode_callerid(redirecting, lv);
 }
 
-/* TS 04.08 10.5.4.21b: encode 'redirecting number' */
+/*! \brief Encode TS 04.08 Redirecting Number IE (10.5.4.21b) */
 int gsm48_encode_redirecting(struct msgb *msg,
 			      const struct gsm_mncc_number *redirecting)
 {
 	return gsm48_encode_callerid(msg, GSM48_IE_REDIR_BCD, 19, redirecting);
 }
 
-/* TS 04.08 10.5.4.15: decode 'facility' */
+/*! \brief Decode TS 04.08 Facility IE (10.5.4.15) */
 int gsm48_decode_facility(struct gsm_mncc_facility *facility,
 			   const uint8_t *lv)
 {
@@ -549,7 +596,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.15: encode 'facility' */
+/*! \brief Encode TS 04.08 Facility IE (10.5.4.15) */
 int gsm48_encode_facility(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_facility *facility)
 {
@@ -568,7 +615,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.20: decode 'notify' */
+/*! \brief Decode TS 04.08 Notify IE (10.5.4.20) */
 int gsm48_decode_notify(int *notify, const uint8_t *v)
 {
 	*notify = v[0] & 0x7f;
@@ -576,7 +623,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.20: encode 'notify' */
+/*! \brief Encode TS 04.08 Notify IE (10.5.4.20) */
 int gsm48_encode_notify(struct msgb *msg, int notify)
 {
 	msgb_v_put(msg, notify | 0x80);
@@ -584,7 +631,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.23: decode 'signal' */
+/*! \brief Decode TS 04.08 Signal IE (10.5.4.23) */
 int gsm48_decode_signal(int *signal, const uint8_t *v)
 {
 	*signal = v[0];
@@ -592,7 +639,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.23: encode 'signal' */
+/*! \brief Encode TS 04.08 Signal IE (10.5.4.23) */
 int gsm48_encode_signal(struct msgb *msg, int signal)
 {
 	msgb_tv_put(msg, GSM48_IE_SIGNAL, signal);
@@ -600,7 +647,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.17: decode 'keypad' */
+/*! \brief Decode TS 04.08 Keypad IE (10.5.4.17) */
 int gsm48_decode_keypad(int *keypad, const uint8_t *lv)
 {
 	uint8_t in_len = lv[0];
@@ -613,7 +660,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.17: encode 'keypad' */
+/*! \brief Encode TS 04.08 Keypad IE (10.5.4.17) */
 int gsm48_encode_keypad(struct msgb *msg, int keypad)
 {
 	msgb_tv_put(msg, GSM48_IE_KPD_FACILITY, keypad);
@@ -621,7 +668,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.21: decode 'progress' */
+/*! \brief Decode TS 04.08 Progress IE (10.5.4.21) */
 int gsm48_decode_progress(struct gsm_mncc_progress *progress,
 			   const uint8_t *lv)
 {
@@ -637,7 +684,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.21: encode 'progress' */
+/*! \brief Encode TS 04.08 Progress IE (10.5.4.21) */
 int gsm48_encode_progress(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_progress *p)
 {
@@ -654,7 +701,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.25: decode 'user-user' */
+/*! \brief Decode TS 04.08 User-User IE (10.5.4.25) */
 int gsm48_decode_useruser(struct gsm_mncc_useruser *uu,
 			   const uint8_t *lv)
 {
@@ -680,7 +727,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.25: encode 'useruser' */
+/*! \brief Encode TS 04.08 User-User IE (10.5.4.25) */
 int gsm48_encode_useruser(struct msgb *msg, int lv_only,
 			   const struct gsm_mncc_useruser *uu)
 {
@@ -700,7 +747,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.24: decode 'ss version' */
+/*! \brief Decode TS 04.08 SS Version IE (10.5.4.24) */
 int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv,
 			    const uint8_t *lv)
 {
@@ -715,7 +762,7 @@
 	return 0;
 }
 
-/* TS 04.08 10.5.4.24: encode 'ss version' */
+/*! \brief Encode TS 04.08 SS Version IE (10.5.4.24) */
 int gsm48_encode_ssversion(struct msgb *msg,
 			   const struct gsm_mncc_ssversion *ssv)
 {
@@ -733,7 +780,7 @@
 
 /* decode 'more data' does not require a function, because it has no value */
 
-/* TS 04.08 10.5.4.19: encode 'more data' */
+/*! \brief Encode TS 04.08 More Data IE (10.5.4.19) */
 int gsm48_encode_more(struct msgb *msg)
 {
 	uint8_t *ie;
@@ -756,7 +803,11 @@
 	return res;
 }
 
-/* decode "Cell Channel Description" (10.5.2.1b) and other frequency lists */
+/*! \brief Decode TS 04.08 Cell Channel Description IE (10.5.2.1b) and other frequency lists
+ *  \param[out] f Caller-provided output memory
+ *  \param[in] cd Cell Channel Description IE
+ *  \param[in] len Length of \a cd in bytes
+ *  \returns 0 on success; negative on error */
 int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd,
 			   uint8_t len, uint8_t mask, uint8_t frqt)
 {
@@ -1190,3 +1241,4 @@
 
 	return 0;
 }
+/*! @} */
diff --git a/src/gsm/gsm_04_08_gprs.c b/src/gsm/gsm_04_08_gprs.c
index 5fef208..bd986d7 100644
--- a/src/gsm/gsm_04_08_gprs.c
+++ b/src/gsm/gsm_04_08_gprs.c
@@ -26,9 +26,11 @@
 
 #include <stdbool.h>
 
-/* Protocol related stuff, should go into libosmocore */
+/*! \addtogroup gsm0408
+ *  @{
+ */
 
-/* 10.5.5.14 GPRS MM Cause / Table 10.5.147 */
+/*! \brief 10.5.5.14 GPRS MM Cause / Table 10.5.147 */
 const struct value_string gsm48_gmm_cause_names_[] = {
 	{ GMM_CAUSE_IMSI_UNKNOWN,	"IMSI unknown in HLR" },
 	{ GMM_CAUSE_ILLEGAL_MS,		"Illegal MS" },
@@ -73,7 +75,7 @@
 
 const struct value_string *gsm48_gmm_cause_names = gsm48_gmm_cause_names_;
 
-/* 10.5.6.6 SM Cause / Table 10.5.157 */
+/*! \brief 10.5.6.6 SM Cause / Table 10.5.157 */
 const struct value_string gsm48_gsm_cause_names_[] = {
 	{ GSM_CAUSE_OPER_DET_BARR, "Operator Determined Barring" },
 	{ GSM_CAUSE_MBMS_CAP_INSUF, "MBMS bearer capabilities insufficient for the service" },
@@ -140,6 +142,7 @@
 	}
 }
 
+/*! \brief String names of GMM message types */
 const struct value_string gprs_msgt_gmm_names[] = {
 	{ GSM48_MT_GMM_ATTACH_REQ,		"ATTACH REQUEST" },
 	{ GSM48_MT_GMM_ATTACH_ACK,		"ATTACH ACK" },
@@ -164,7 +167,7 @@
 	{ 0, NULL }
 };
 
-/* 10.5.5.2 */
+/*! \brief String names of GPRS Attach types according to 10.5.5.2 */
 const struct value_string gprs_att_t_strs_[] = {
 	{ GPRS_ATT_T_ATTACH,		"GPRS attach" },
 	{ GPRS_ATT_T_ATT_WHILE_IMSI,	"GPRS attach while IMSI attached" },
@@ -174,6 +177,7 @@
 
 const struct value_string *gprs_att_t_strs = gprs_att_t_strs_;
 
+/*! \brief String names of GPRS Location Update Types */
 const struct value_string gprs_upd_t_strs_[] = {
 	{ GPRS_UPD_T_RA,		"RA updating" },
 	{ GPRS_UPD_T_RA_LA,		"combined RA/LA updating" },
@@ -184,7 +188,7 @@
 
 const struct value_string *gprs_upd_t_strs = gprs_upd_t_strs_;
 
-/* 10.5.5.5 */
+/*! \brief String names of GMM MO Detach Types according to 10.5.5.5 */
 const struct value_string gprs_det_t_mo_strs_[] = {
 	{ GPRS_DET_T_MO_GPRS,		"GPRS detach" },
 	{ GPRS_DET_T_MO_IMSI,		"IMSI detach" },
@@ -194,6 +198,7 @@
 
 const struct value_string *gprs_det_t_mo_strs = gprs_det_t_mo_strs_;
 
+/*! \brief String names of GMM MT Detach Types according to 10.5.5.5 */
 const struct value_string gprs_det_t_mt_strs_[] = {
 	{ GPRS_DET_T_MT_REATT_REQ,	"re-attach required" },
 	{ GPRS_DET_T_MT_REATT_NOTREQ,	"re-attach not required" },
@@ -203,6 +208,7 @@
 
 const struct value_string *gprs_det_t_mt_strs = gprs_det_t_mt_strs_;
 
+/*! \brief String names of GMM Service Types */
 const struct value_string gprs_service_t_strs_[] = {
 	{ GPRS_SERVICE_T_SIGNALLING,	"signalling" },
 	{ GPRS_SERVICE_T_DATA,		"data" },
@@ -213,3 +219,5 @@
 };
 
 const struct value_string *gprs_service_t_strs = gprs_service_t_strs_;
+
+/*! @} */
diff --git a/src/gsm/gsm_utils.c b/src/gsm/gsm_utils.c
index d16adf7..9cb5df6 100644
--- a/src/gsm/gsm_utils.c
+++ b/src/gsm/gsm_utils.c
@@ -134,7 +134,10 @@
 	return -1;
 }
 
-/* Compute the number of octets from the number of septets, for instance: 47 septets needs 41,125 = 42 octets */
+/*! \brife Compute number of octets from number of septets,
+ *  for instance: 47 septets needs 41,125 = 42 octets
+ *  \param[in sept_len Number of Septets
+ *  \returns Number of octets required */
 uint8_t gsm_get_octet_len(const uint8_t sept_len){
 	int octet_len = (sept_len * 7) / 8;
 	if ((sept_len * 7) % 8 != 0)
@@ -143,7 +146,13 @@
 	return octet_len;
 }
 
-/* GSM 03.38 6.2.1 Character unpacking */
+/*! \brief TS 03.38 7-bit Character unpacking (6.2.1)
+ *  \param[out] text Caller-provided output text buffer
+ *  \param[in] n Length of \a text
+ *  \param[in] user_data Input Data (septets)
+ *  \param[in] septet_l Number of septets in \a user_data
+ *  \param[in] ud_hdr_ind User Data Header present in data
+ *  \returns number of bytes written to \a text */
 int gsm_7bit_decode_n_hdr(char *text, size_t n, const uint8_t *user_data, uint8_t septet_l, uint8_t ud_hdr_ind)
 {
 	unsigned shift = 0;
@@ -201,11 +210,13 @@
 	return text - text_buf_begin;
 }
 
+/*! \brief Decode 7bit GSM Alphabet */
 int gsm_7bit_decode_n(char *text, size_t n, const uint8_t *user_data, uint8_t septet_l)
 {
 	return gsm_7bit_decode_n_hdr(text, n, user_data, septet_l, 0);
 }
 
+/*! \brief Decode 7bit GSM Alphabet (USSD) */
 int gsm_7bit_decode_n_ussd(char *text, size_t n, const uint8_t *user_data, uint8_t length)
 {
 	int nchars;
@@ -218,7 +229,15 @@
 	return nchars;
 }
 
-/* GSM 03.38 6.2.1 Prepare character packing */
+/*! \brief Encode a ASCII characterrs as 7-bit GSM alphabet (TS 03.38)
+ *
+ *  This function converts a zero-terminated input string \a data from
+ *  ASCII into octet-aligned 7-bit GSM characters. No packing is
+ *  performed.
+ *
+ *  \param[out] result caller-allocated output buffer
+ *  \param[in] data input data, ASCII
+ *  \returns number of octets used in \a result */
 int gsm_septet_encode(uint8_t *result, const char *data)
 {
 	int i, y = 0;
@@ -247,7 +266,12 @@
 	return y;
 }
 
-/* 7bit to octet packing */
+/*! \brief GSM Default Alphabet 7bit to octet packing
+ *  \param[out] result Caller-provided output buffer
+ *  \param[in] rdata Input data septets
+ *  \param[in] septet_len Length of \a rdata
+ *  \param[in] padding padding bits at start
+ *  \returns number of bytes used in \a result */
 int gsm_septets2octets(uint8_t *result, const uint8_t *rdata, uint8_t septet_len, uint8_t padding)
 {
 	int i = 0, z = 0;
@@ -293,7 +317,12 @@
 	return z;
 }
 
-/* GSM 03.38 6.2.1 Character packing */
+/*! \brief GSM 7-bit alphabet TS 03.38 6.2.1 Character packing
+ *  \param[out] result Caller-provided output buffer
+ *  \param[in] n Maximum length of \a result in bytes
+ *  \param[in] data octet-aligned string
+ *  \param[out] octets Number of octets encoded
+ *  \returns number of septets encoded */
 int gsm_7bit_encode_n(uint8_t *result, size_t n, const char *data, int *octets)
 {
 	int y = 0;
@@ -332,6 +361,12 @@
 	return y;
 }
 
+/*! \brief Encode according to GSM 7-bit alphabet (TS 03.38 6.2.1) for USSD
+ *  \param[out] result Caller-provided output buffer
+ *  \param[in] n Maximum length of \a result in bytes
+ *  \param[in] data octet-aligned string
+ *  \param[out] octets Number of octets encoded
+ *  \returns number of septets encoded */
 int gsm_7bit_encode_n_ussd(uint8_t *result, size_t n, const char *data, int *octets)
 {
 	int y;
@@ -368,7 +403,10 @@
 	return 3;
 }
 
-/* convert power class to dBm according to GSM TS 05.05 */
+/*! \brief Convert power class to dBm according to GSM TS 05.05
+ *  \param[in] band GSM frequency band
+ *  \param[in] class GSM power class
+ *  \returns maximum transmit power of power class in dBm */
 unsigned int ms_class_gmsk_dbm(enum gsm_band band, int class)
 {
 	switch (band) {
@@ -409,8 +447,11 @@
 	return -EINVAL;
 }
 
-/* determine power control level for given dBm value, as indicated
- * by the tables in chapter 4.1.1 of GSM TS 05.05 */
+/*! \brief determine power control level for given dBm value, as indicated
+ *  by the tables in chapter 4.1.1 of GSM TS 05.05
+ *  \param[in] GSM frequency band
+ *  \param[in] dbm RF power value in dBm
+ *  \returns TS 05.05 power control level */
 int ms_pwr_ctl_lvl(enum gsm_band band, unsigned int dbm)
 {
 	switch (band) {
@@ -459,6 +500,10 @@
 	return -EINVAL;
 }
 
+/*! \brief Convert TS 05.05 power level to absolute dBm value
+ *  \param[in] band GSM frequency band
+ *  \param[in] lvl TS 05.05 power control level
+ *  \returns RF power level in dBm */
 int ms_pwr_dbm(enum gsm_band band, uint8_t lvl)
 {
 	lvl &= 0x1f;
@@ -497,7 +542,9 @@
 	return -EINVAL;
 }
 
-/* According to TS 05.08 Chapter 8.1.4 */
+/*! \brief Convert TS 05.08 RxLev to dBm (TS 05.08 Chapter 8.1.4)
+ *  \param[in] rxlev TS 05.08 RxLev value
+ *  \returns Received RF power in dBm */
 int rxlev2dbm(uint8_t rxlev)
 {
 	if (rxlev > 63)
@@ -506,7 +553,9 @@
 	return -110 + rxlev;
 }
 
-/* According to TS 05.08 Chapter 8.1.4 */
+/*! \brief Convert RF signal level in dBm to TS 05.08 RxLev (TS 05.08 Chapter 8.1.4)
+ *  \param[in] dbm RF signal level in dBm
+ *  \returns TS 05.08 RxLev value */
 uint8_t dbm2rxlev(int dbm)
 {
 	int rxlev = dbm + 110;
@@ -519,6 +568,7 @@
 	return rxlev;
 }
 
+/*! \brief Return string name of a given GSM Band */
 const char *gsm_band_name(enum gsm_band band)
 {
 	switch (band) {
@@ -542,6 +592,7 @@
 	return "invalid";
 }
 
+/*! \brief Parse string name of a GSM band */
 enum gsm_band gsm_band_parse(const char* mhz)
 {
 	while (*mhz && !isdigit(*mhz))
@@ -572,6 +623,10 @@
 	}
 }
 
+/*! \brief Resolve GSM band from ARFCN
+ *  In Osmocom, we use the highest bit of the \a arfcn to indicate PCS
+ *  \param[in] arfcn Osmocom ARFCN, highest bit determines PCS mode
+ *  \returns GSM Band */
 enum gsm_band gsm_arfcn2band(uint16_t arfcn)
 {
 	int is_pcs = arfcn & ARFCN_PCS;
@@ -621,7 +676,10 @@
 	{ /* Guard */ }
 };
 
-/* Convert an ARFCN to the frequency in MHz * 10 */
+/*! \brief Convert an ARFCN to the frequency in MHz * 10
+ *  \param[in] arfcn GSM ARFCN to convert
+ *  \param[in] uplink Uplink (1) or Downlink (0) frequency
+ *  \returns Frequency in units of 1/10ths of MHz (100kHz) */
 uint16_t gsm_arfcn2freq10(uint16_t arfcn, int uplink)
 {
 	struct gsm_freq_range *r;
@@ -645,7 +703,10 @@
 	return uplink ? freq10_ul : freq10_dl;
 }
 
-/* Convert a Frequency in MHz * 10 to ARFCN */
+/*! \brief Convert a Frequency in MHz * 10 to ARFCN
+ *  \param[in] freq10 Frequency in units of 1/10ths of MHz (100kHz)
+ *  \param[in] uplink Frequency is Uplink (1) or Downlink (0)
+ *  \returns ARFCN in case of success; 0xffff on error */
 uint16_t gsm_freq102arfcn(uint16_t freq10, int uplink)
 {
 	struct gsm_freq_range *r;
@@ -675,6 +736,9 @@
 	return arfcn;
 }
 
+/*! \brief Parse GSM Frame Number into struct \ref gsm_time
+ *  \param[out] time Caller-provided memory for \ref gsm_time
+ *  \param[in] fn GSM Frame Number */
 void gsm_fn2gsmtime(struct gsm_time *time, uint32_t fn)
 {
 	time->fn = fn;
@@ -684,13 +748,18 @@
 	time->tc = (time->fn / 51) % 8;
 }
 
+/*! \brief Encode decoded \ref gsm_time to Frame Number
+ *  \param[in] time GSM Time in decoded structure
+ *  \returns GSM Frame Number */
 uint32_t gsm_gsmtime2fn(struct gsm_time *time)
 {
 	/* TS 05.02 Chapter 4.3.3 TDMA frame number */
 	return (51 * ((time->t3 - time->t2 + 26) % 26) + time->t3 + (26 * 51 * time->t1));
 }
 
-/*! \brief append range1024 encoded data to bit vector */
+/*! \brief append range1024 encoded data to bit vector
+ *  \param[out] bv Caller-provided output bit-vector
+ *  \param[in] r Input Range1024 sructure */
 void bitvec_add_range1024(struct bitvec *bv, const struct gsm48_range_1024 *r)
 {
 	bitvec_set_uint(bv, r->w1_hi, 2);
@@ -724,7 +793,7 @@
 	bitvec_set_uint(bv, r->w16, 6);
 }
 
-/* TS 23.003 Chapter 2.6 */
+/*! \brief Determine GPRS TLLI Type (TS 23.003 Chapter 2.6) */
 int gprs_tlli_type(uint32_t tlli)
 {
 	if ((tlli & 0xc0000000) == 0xc0000000)
@@ -743,6 +812,10 @@
 	return TLLI_RESERVED;
 }
 
+/*! \brief Determine TLLI from P-TMSI
+ *  \param[in] p_tmsi P-TMSI
+ *  \param[in] type TLLI Type we want to derive from \a p_tmsi
+ *  \returns TLLI of given type */
 uint32_t gprs_tmsi2tlli(uint32_t p_tmsi, enum gprs_tlli_type type)
 {
 	uint32_t tlli;
diff --git a/src/gsm/gsup.c b/src/gsm/gsup.c
index a813ed8..3cac201 100644
--- a/src/gsm/gsup.c
+++ b/src/gsm/gsup.c
@@ -31,6 +31,11 @@
 
 #include <stdint.h>
 
+/*! \addtogroup gsup
+ *  @{
+ *  \brief Osmocom Generic Subscriber Update Protocol
+ */
+
 const struct value_string osmo_gsup_message_type_names[] = {
 	OSMO_VALUE_STRING(OSMO_GSUP_MSGT_UPDATE_LOCATION_REQUEST),
 	OSMO_VALUE_STRING(OSMO_GSUP_MSGT_UPDATE_LOCATION_ERROR),
@@ -536,3 +541,5 @@
 		msgb_tlv_put(msg, OSMO_GSUP_CN_DOMAIN_IE, 1, &dn);
 	}
 }
+
+/*! @} */
diff --git a/src/gsm/ipa.c b/src/gsm/ipa.c
index fa6a8b0..5c37d64 100644
--- a/src/gsm/ipa.c
+++ b/src/gsm/ipa.c
@@ -41,6 +41,11 @@
 #include <osmocom/gsm/protocol/ipaccess.h>
 #include <osmocom/gsm/ipa.h>
 
+/*! \addtogroup ipa
+ *  @{
+ *  \brief IPA Multiplex utility routines
+ */
+
 #define IPA_ALLOC_SIZE 1200
 
 /*
@@ -581,3 +586,5 @@
 		return NULL;
 	return nmsg;
 }
+
+/*! @} */
diff --git a/src/gsm/lapd_core.c b/src/gsm/lapd_core.c
index 310df65..b7a9539 100644
--- a/src/gsm/lapd_core.c
+++ b/src/gsm/lapd_core.c
@@ -23,6 +23,7 @@
 
 /*! \addtogroup lapd
  *  @{
+ *  \brief Osmocom LAPD core, used for Q.921, LAPDm and others
  */
 
 /*! \file lapd_core.c */
diff --git a/src/gsm/lapdm.c b/src/gsm/lapdm.c
index 99099d1..8ec942f 100644
--- a/src/gsm/lapdm.c
+++ b/src/gsm/lapdm.c
@@ -23,6 +23,7 @@
 
 /*! \addtogroup lapdm
  *  @{
+ *  \brief GSM LAPDm (TS 04.06) implementation
  */
 
 /*! \file lapdm.c */
diff --git a/src/gsm/oap.c b/src/gsm/oap.c
index 1494a6a..5706e8f 100644
--- a/src/gsm/oap.c
+++ b/src/gsm/oap.c
@@ -28,6 +28,11 @@
 
 #include <stdint.h>
 
+/*! \addtogroup oap
+ *  @{
+ *  \brief Osmocom Authentication Protocol
+ */
+
 /*! \brief Decode OAP message data.
  * \param[out] oap_msg  Parsed data is written to this instance.
  * \param[in] data  Pointer to the data buffer containing the OAP message.
@@ -182,3 +187,5 @@
 
 	msg->l2h = msg->data;
 }
+
+/*! @} */
diff --git a/src/gsm/rsl.c b/src/gsm/rsl.c
index 910e848..5bdb006 100644
--- a/src/gsm/rsl.c
+++ b/src/gsm/rsl.c
@@ -30,6 +30,7 @@
 
 /*! \addtogroup rsl
  *  @{
+ *  \brief GSM Radio Signalling Link (TS 08.58)
  */
 
 /*! \file rsl.c */
@@ -39,7 +40,9 @@
 /*! \brief Headroom size for RSL \ref msgb_alloc */
 #define RSL_ALLOC_HEADROOM	56
 
-/*! \brief Initialize a RSL RLL header */
+/*! \brief Initialize a RSL RLL header
+ *  \param[out] dh Caller-allocated RSL RLL header
+ *  \param[in] msg_type Message Type */
 void rsl_init_rll_hdr(struct abis_rsl_rll_hdr *dh, uint8_t msg_type)
 {
 	dh->c.msg_discr = ABIS_RSL_MDISC_RLL;
@@ -48,7 +51,9 @@
 	dh->ie_link_id = RSL_IE_LINK_IDENT;
 }
 
-/*! \brief Initialize a RSL Common Channel header */
+/*! \brief Initialize a RSL Common Channel header
+ *  \param[out] ch Caller-allocated RSL Common Channel Header
+ *  \param[in] msg_type Message Type */
 void rsl_init_cchan_hdr(struct abis_rsl_cchan_hdr *ch, uint8_t msg_type)
 {
 	ch->c.msg_discr = ABIS_RSL_MDISC_COM_CHAN;
@@ -137,7 +142,11 @@
 	},
 };
 
-/*! \brief Encode channel number as per Section 9.3.1 */
+/*! \brief Encode channel number as per Section 9.3.1
+ *  \param[in] Channel Type (RSL_CHAN_...)
+ *  \param[in] subch Sub-Channel within Channel
+ *  \param[in] timeslot Air interface timeslot
+ *  \returns RSL Channel Number (TS 08.58 9.3.1) */
 uint8_t rsl_enc_chan_nr(uint8_t type, uint8_t subch, uint8_t timeslot)
 {
 	uint8_t ret;
@@ -455,7 +464,12 @@
 	}
 }
 
-/*! \brief Push a RSL RLL header onto an existing msgb */
+/*! \brief Push a RSL RLL header onto an existing msgb
+ *  \param msg Message Buffer to which RLL header shall be pushed
+ *  \param[in] msg_type RSL Message Type
+ *  \param[in] chan_nr RSL Channel Number
+ *  \param[in] link_id RSL Link Identifier
+ *  \param[in] transparent Transparent to BTS (1) or not (0) */
 void rsl_rll_push_hdr(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 		      uint8_t link_id, int transparent)
 {
@@ -472,7 +486,12 @@
 	msg->l2h = (uint8_t *)rh;
 }
 
-/*! \brief Push a RSL RLL header with L3_INFO IE */
+/*! \brief Wrap msgb in L3 Info IE and push a RSL RLL header
+ *  \param[in] msg Message Buffer to which L3 Header shall be appended
+ *  \param[in] msg_type RSL Message Type
+ *  \param[in] chan_hr RSL Channel Number
+ *  \param[in] link_id Link Identififer
+ *  \param[in] transparent Transparent to BTS (1) or not (0) */
 void rsl_rll_push_l3(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 		     uint8_t link_id, int transparent)
 {
@@ -488,7 +507,12 @@
 	rsl_rll_push_hdr(msg, msg_type, chan_nr, link_id, transparent);
 }
 
-/*! \brief Create msgb with RSL RLL header */
+/*! \brief Create msgb with RSL RLL header
+ *  \param[in] msg_type RSL Message Type
+ *  \param[in] chan_nr RSL Channel Number
+ *  \param[in] link_id RSL Link Identifier
+ *  \param[in] transparent Transparent to BTS (1) or not (0)
+ *  \returns callee-allocated msgb; NULL on error */
 struct msgb *rsl_rll_simple(uint8_t msg_type, uint8_t chan_nr,
 			    uint8_t link_id, int transparent)
 {
@@ -515,6 +539,7 @@
 	return msg;
 }
 
+/*! \brief TLV parser definitions for IPA embedded IEs */
 const struct tlv_definition rsl_ipac_eie_tlvdef = {
 	.def = {
 		[RSL_IPAC_EIE_RXLEV]		= { TLV_TYPE_TV },
@@ -541,6 +566,7 @@
 	},
 };
 
+/*! \brief String names of RSL Channel Activation Types */
 const struct value_string rsl_act_type_names[] = {
 	{ RSL_ACT_TYPE_INITIAL,	"INITIAL" },
 	{ RSL_ACT_TYPE_REACT,	"REACT" },
diff --git a/src/gsm/tlv_parser.c b/src/gsm/tlv_parser.c
index 4cc43f6..d7604c6 100644
--- a/src/gsm/tlv_parser.c
+++ b/src/gsm/tlv_parser.c
@@ -25,7 +25,22 @@
 
 /*! \addtogroup tlv
  *  @{
+ *  \brief Osmocom TLV Parser
+ *
+ *  The Osmocom TLV parser is intended to operate as a low-level C
+ *  implementation without dynamic memory allocations.  Basically, it
+ *  iterates over the IE (Information Elements) of the message and fills
+ *  an array of pointers, indexed by the IEI (IE Identifier).  The
+ *  parser output is thus an array of pointers to the start of the
+ *  respective IE inside the message.
+ *
+ *  The TLV parser is configured by a TLV parser definition, which
+ *  determines which if the IEIs for a given protocol are of which
+ *  particular type.  Types are e.g. TV (Tag + single byte value), Tag +
+ *  fixed-length value, TLV with 8bit length, TLV with 16bit length, TLV
+ *  with variable-length length field, etc.
  */
+
 /*! \file tlv_parser.c */
 
 struct tlv_definition tvlv_att_def;
@@ -262,7 +277,9 @@
 	return num_parsed;
 }
 
-/*! \brief take a master (src) tlvdev and fill up all empty slots in 'dst' */
+/*! \brief take a master (src) tlvdev and fill up all empty slots in 'dst'
+ *  \param dst TLV parser definition that is to be patched
+ *  \param[in] src TLV parser definition whose content is patched into \a dst */
 void tlv_def_patch(struct tlv_definition *dst, const struct tlv_definition *src)
 {
 	int i;
diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c
index 74f3b48..64b54f3 100644
--- a/src/gsmtap_util.c
+++ b/src/gsmtap_util.c
@@ -43,6 +43,7 @@
 
 /*! \addtogroup gsmtap
  *  @{
+ *  \brief GSMTAP utility routines. Encapsulates GSM messages over UDP
  */
 /*! \file gsmtap_util.c */
 
diff --git a/src/logging.c b/src/logging.c
index 0d2b6da..3b3dd05 100644
--- a/src/logging.c
+++ b/src/logging.c
@@ -22,6 +22,7 @@
 
 /* \addtogroup logging
  * @{
+ * \brief libosmocore Logging sub-system
  */
 
 /* \file logging.c */
diff --git a/src/logging_gsmtap.c b/src/logging_gsmtap.c
index f37f8e7..7358bf6 100644
--- a/src/logging_gsmtap.c
+++ b/src/logging_gsmtap.c
@@ -23,7 +23,13 @@
  *  @{
  */
 
-/*! \file logging_gsmtap.c */
+/*! \file logging_gsmtap.c
+ *  \brief libosmocore log output encapsulated in GSMTAP
+ *
+ *  Encapsulating the log output inside GSMTAP frames allows us to
+ *  observer protocol traces (of Um, Abis, A or any other interface in
+ *  the Osmocom world) with synchronous interspersed log messages.
+ */
 
 #include "../config.h"
 
diff --git a/src/logging_syslog.c b/src/logging_syslog.c
index 5b0ae5f..6fe3c71 100644
--- a/src/logging_syslog.c
+++ b/src/logging_syslog.c
@@ -23,7 +23,9 @@
  *  @{
  */
 
-/*! \file logging_syslog.c */
+/*! \file logging_syslog.c
+ *  \brief libosmocore logging output via syslog
+ */
 
 #include "../config.h"
 
diff --git a/src/loggingrb.c b/src/loggingrb.c
index bd093b7..3fb38ca 100644
--- a/src/loggingrb.c
+++ b/src/loggingrb.c
@@ -23,7 +23,9 @@
  *  @{
  */
 
-/*! \file loggingrb.c */
+/*! \file loggingrb.c
+ *  \brief libosmocore logging backend for a ring-buffer of last log messages
+ */
 
 #include <osmocom/core/strrb.h>
 #include <osmocom/core/logging.h>
diff --git a/src/macaddr.c b/src/macaddr.c
index ceb1e0a..e5db8cf 100644
--- a/src/macaddr.c
+++ b/src/macaddr.c
@@ -24,7 +24,9 @@
  *  @{
  */
 
-/*! \file loggingrb.c */
+/*! \file macaddr.c
+ *  \brief MAC address utility routines
+ */
 
 #include "config.h"
 
diff --git a/src/msgb.c b/src/msgb.c
index a27100c..136ad88 100644
--- a/src/msgb.c
+++ b/src/msgb.c
@@ -20,10 +20,35 @@
 
 /*! \addtogroup msgb
  *  @{
+ *  \brief libosmocore message buffers, inspired by Linux kernel skbuff
+ *
+ *  Inspired by the 'struct skbuff' of the Linux kernel, we implement a
+ *  'struct msgb' which we use for handling network
+ *  packets aka messages aka PDUs.
+ *
+ *  A msgb consists of
+ *  	* a header with some metadata, such as
+ *  	  * a linked list header for message queues or the like
+ *  	  * pointers to the headers of various protocol layers inside
+ *  	    the packet
+ *  	* a data section consisting of
+ *  	  * headroom, i.e. space in front of the message, to allow
+ *  	    for additional headers being pushed in front of the current
+ *  	    data
+ *  	  * the curently occupied data for the message
+ *  	  * tailroom, i.e. space at the end of the message, to
+ *  	    allow more data to be added after the end of the current
+ *  	    data
+ *
+ *  We have plenty of utility functions around the \ref msgb:
+ *  	* allocation / release
+ *  	* enqueue / dequeue from/to message queues
+ *  	* prepending (pushing) and appending (putting) data
+ *  	* copying / resizing
+ *  	* hex-dumping to a string for debug purposes
  */
 
-/*! \file msgb.c
- */
+/*! \file msgb.c */
 
 #include <unistd.h>
 #include <string.h>
diff --git a/src/plugin.c b/src/plugin.c
index 52887ac..71df88b 100644
--- a/src/plugin.c
+++ b/src/plugin.c
@@ -20,6 +20,10 @@
  *
  */
 
+/*! \addtogroup utils
+ *  @{
+ */
+
 /*! \file plugin.c
  *  \brief Routines for loading and managing shared library plug-ins.
  */
@@ -69,3 +73,5 @@
 	return 0;
 }
 #endif /* HAVE_DLFCN_H */
+
+/*! @} */
diff --git a/src/rate_ctr.c b/src/rate_ctr.c
index 3ccd065..47067fb 100644
--- a/src/rate_ctr.c
+++ b/src/rate_ctr.c
@@ -22,6 +22,7 @@
 
 /*! \addtogroup rate_ctr
  *  @{
+ *  \brief conters about events and their event rates
  */
 
 /*! \file rate_ctr.c */
diff --git a/src/select.c b/src/select.c
index afc8198..bdd53b2 100644
--- a/src/select.c
+++ b/src/select.c
@@ -36,11 +36,10 @@
 
 /*! \addtogroup select
  *  @{
+ *  \brief select() loop abstraction
  */
 
-/*! \file select.c
- *  \brief select loop abstraction
- */
+/*! \file select.c */
 
 static int maxfd = 0;
 static LLIST_HEAD(osmo_fds);
diff --git a/src/sercomm.c b/src/sercomm.c
index 2f693ef..33d4853 100644
--- a/src/sercomm.c
+++ b/src/sercomm.c
@@ -22,6 +22,7 @@
 
 /*! \addtogroup sercomm
  *  @{
+ *  \brief Serial communications layer, based on HDLC
  */
 
 /*! \file sercomm.c
diff --git a/src/serial.c b/src/serial.c
index 05bdc86..51a32bb 100644
--- a/src/serial.c
+++ b/src/serial.c
@@ -24,11 +24,10 @@
 
 /*! \addtogroup serial
  *  @{
+ *  \brief Osmocom serial port helpers
  */
 
-/*! \file serial.c
- * Osmocom serial port helpers
- */
+/*! \file serial.c */
 
 #include <errno.h>
 #include <fcntl.h>
diff --git a/src/signal.c b/src/signal.c
index 8402591..1d11617 100644
--- a/src/signal.c
+++ b/src/signal.c
@@ -27,7 +27,9 @@
 
 /*! \addtogroup signal
  *  @{
+ *  \brief Generic signalling/notification infrastructure
  */
+
 /*! \file signal.c */
 
 
diff --git a/src/socket.c b/src/socket.c
index 9d22d61..6fa05a8 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -23,12 +23,11 @@
 
 /*! \addtogroup socket
  *  @{
- */
-
-/*! \file socket.c
  *  \brief Osmocom socket convenience functions
  */
 
+/*! \file socket.c */
+
 #ifdef HAVE_SYS_SOCKET_H
 
 #include <osmocom/core/logging.h>
diff --git a/src/strrb.c b/src/strrb.c
index 069a699..69c4dda 100644
--- a/src/strrb.c
+++ b/src/strrb.c
@@ -21,6 +21,10 @@
  *
  */
 
+/*! \addtogroup utils
+ *  @{
+ */
+
 /*! \file strrb.c
  *  \brief Lossy string ringbuffer for logging; keeps newest messages.
  */
@@ -170,3 +174,5 @@
 	}
 	return ret;
 }
+
+/*! @} */
diff --git a/src/timer.c b/src/timer.c
index a8cd42b..72176b8 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -26,10 +26,10 @@
 
 /*! \addtogroup timer
  *  @{
+ *  \brief Osmocom timer abstraction; modelled after linux kernel timers
  */
 
-/*! \file timer.c
- */
+/*! \file timer.c */
 
 #include <assert.h>
 #include <string.h>
diff --git a/src/utils.c b/src/utils.c
index 1a4aab4..e7c6bcf 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -33,6 +33,7 @@
 
 /*! \addtogroup utils
  * @{
+ * \brief various utility routines
  */
 
 /*! \file utils.c */
diff --git a/src/vty/command.c b/src/vty/command.c
index 587bd62..e50706e 100644
--- a/src/vty/command.c
+++ b/src/vty/command.c
@@ -42,7 +42,8 @@
 #include <osmocom/core/utils.h>
 
 /*! \addtogroup command
- * @{
+ *  @{
+ *  \brief VTY command handling
  */
 /*! \file command.c */
 
diff --git a/src/vty/fsm_vty.c b/src/vty/fsm_vty.c
index 422de9d..3824fe8 100644
--- a/src/vty/fsm_vty.c
+++ b/src/vty/fsm_vty.c
@@ -33,6 +33,16 @@
 #include <osmocom/core/logging.h>
 #include <osmocom/core/linuxlist.h>
 
+/*! \addtogroup fsm
+ *  @{
+ *  \brief VTY interface for Osmocom FSM
+ *
+ *  This is code implementing generic VTY access to Osmocom FSMs from
+ *  libosmocore.  This means that any application can expose all state
+ *  of all instances of all registered FSM classes by calling a single
+ *  command during startup: \ref osmo_fsm_vty_add_cmds
+ */
+
 /* we don't want to add this to a public header file; this is simply
  * exported by libosmocore and used by libmsomvty but not for public
  * consumption. */
@@ -175,3 +185,5 @@
 	install_element_ve(&show_fsm_inst_cmd);
 	install_element_ve(&show_fsm_insts_cmd);
 }
+
+/*! @} */
diff --git a/src/vty/logging_vty.c b/src/vty/logging_vty.c
index 7ec212e..8c8a323 100644
--- a/src/vty/logging_vty.c
+++ b/src/vty/logging_vty.c
@@ -39,6 +39,16 @@
 
 #define LOG_STR "Configure logging sub-system\n"
 
+/*! \addtogroup logging
+ *  @{
+ *  \brief Configuration of logging from VTY
+ *
+ *  This module implements functions that permit configuration of
+ *  the libosmocore logging framework from VTY commands.  This applies
+ *  both to logging to the VTY (telnet sessions), as well as logging to
+ *  other targets, such as sysslog, file, gsmtap, ...
+ */
+
 extern const struct log_info *osmo_log_info;
 
 static void _vty_output(struct log_target *tgt,
@@ -778,3 +788,5 @@
 #endif
 	install_element(CONFIG_NODE, &cfg_log_gsmtap_cmd);
 }
+
+/* @} */
diff --git a/src/vty/stats_vty.c b/src/vty/stats_vty.c
index c03546b..af69289 100644
--- a/src/vty/stats_vty.c
+++ b/src/vty/stats_vty.c
@@ -41,6 +41,11 @@
 
 #define SHOW_STATS_STR "Show statistical values\n"
 
+/*! \addtogroup stats
+ *  @{
+ *  \brief VTY interface for statsd / statistic items
+ */
+
 /* containing version info */
 extern struct host host;
 
@@ -571,6 +576,10 @@
 	return 1;
 }
 
+/*! \brief Add stats related commands to the VTY
+ *  Call this once during your application initialization if you would
+ *  like to have stats VTY commands enabled.
+ */
 void osmo_stats_vty_add_cmds()
 {
 	install_element_ve(&show_stats_cmd);
@@ -599,3 +608,5 @@
 
 	install_element_ve(&show_stats_asciidoc_table_cmd);
 }
+
+/*! @} */
diff --git a/src/vty/telnet_interface.c b/src/vty/telnet_interface.c
index 218f9ab..d53881a 100644
--- a/src/vty/telnet_interface.c
+++ b/src/vty/telnet_interface.c
@@ -38,6 +38,12 @@
 
 /*! \addtogroup telnet_interface
  *  @{
+ *  \brief Telnet interface towards Osmocom VTY
+ *
+ *  This module contains the code implementing a telnet server for VTY
+ *  access.  This telnet server gets linked into each libosmovty-using
+ *  process in order to enable interactive command-line introspection,
+ *  interaction and configuration.
  */
 /*! \file telnet_interface.c */
 
diff --git a/src/vty/utils.c b/src/vty/utils.c
index 27c1a85..6772593 100644
--- a/src/vty/utils.c
+++ b/src/vty/utils.c
@@ -82,6 +82,33 @@
 	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, &vctx);
 }
 
+static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_)
+{
+	struct vty_out_context *vctx = vctx_;
+	struct vty *vty = vctx->vty;
+
+	if (ctrg->desc->class_id > vctx->max_level)
+		return 0;
+
+	if (ctrg->idx)
+		vty_out(vty, "%s%s (%d):%s", vctx->prefix,
+			ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE);
+	else
+		vty_out(vty, "%s%s:%s", vctx->prefix,
+			ctrg->desc->group_description, VTY_NEWLINE);
+
+	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx);
+
+	return 0;
+}
+
+/*! @} */
+
+
+/*! \addtogroup stats
+ *  @{
+ */
+
 static int osmo_stat_item_handler(
 	struct osmo_stat_item_group *statg, struct osmo_stat_item *item, void *vctx_)
 {
@@ -135,25 +162,11 @@
 	return 0;
 }
 
-static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_)
-{
-	struct vty_out_context *vctx = vctx_;
-	struct vty *vty = vctx->vty;
+/*! @} */
 
-	if (ctrg->desc->class_id > vctx->max_level)
-		return 0;
-
-	if (ctrg->idx)
-		vty_out(vty, "%s%s (%d):%s", vctx->prefix,
-			ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE);
-	else
-		vty_out(vty, "%s%s:%s", vctx->prefix,
-			ctrg->desc->group_description, VTY_NEWLINE);
-
-	rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx);
-
-	return 0;
-}
+/*! \addtogroup vty
+ *  @{
+ */
 
 static int handle_counter(struct osmo_counter *counter, void *vctx_)
 {
@@ -239,5 +252,4 @@
 	return str;
 }
 
-
 /*! @} */
diff --git a/src/vty/vector.c b/src/vty/vector.c
index c5a99af..b95e15c 100644
--- a/src/vty/vector.c
+++ b/src/vty/vector.c
@@ -27,6 +27,11 @@
 #include <osmocom/core/talloc.h>
 #include <string.h>
 
+/*! \addtogroup vector
+ *  @{
+ *  \brief Generic vector routines, used by VTY internally
+ */
+
 void *tall_vty_vec_ctx;
 
 /* Initialize vector : allocate memory and return vector. */
@@ -190,3 +195,5 @@
 
 	return count;
 }
+
+/*! @} */
diff --git a/src/vty/vty.c b/src/vty/vty.c
index 01d5ec0..2ec9538 100644
--- a/src/vty/vty.c
+++ b/src/vty/vty.c
@@ -14,7 +14,7 @@
  * routines in libosmovty are not thread-safe.  If you must use them in
  * a multi-threaded context, you have to add your own locking.
  *
- * libosmocovty is developed as part of the Osmocom (Open Source Mobile
+ * libosmovty is developed as part of the Osmocom (Open Source Mobile
  * Communications) project, a community-based, collaborative development
  * project to create Free and Open Source implementations of mobile
  * communications systems.  For more information about Osmocom, please
diff --git a/src/write_queue.c b/src/write_queue.c
index c7a4320..1e4cda5 100644
--- a/src/write_queue.c
+++ b/src/write_queue.c
@@ -27,6 +27,7 @@
 
 /*! \addtogroup write_queue
  *  @{
+ *  \brief write queue for writing \ref msgb to sockets/fd's
  */
 
 /*! \file write_queue.c */