diff --git a/src/gsm/a5.c b/src/gsm/a5.c
index f21554f..e906b6d 100644
--- a/src/gsm/a5.c
+++ b/src/gsm/a5.c
@@ -1,12 +1,11 @@
-/*
- * a5.c
- *
- * Full reimplementation of A5/1,2 (split and threadsafe)
+/*! \file a5.c
+ * Full reimplementation of A5/1,2 (split and threadsafe).
  *
  * The logic behind the algorithm is taken from "A pedagogical implementation
  * of the GSM A5/1 and A5/2 "voice privacy" encryption algorithms." by
  * Marc Briceno, Ian Goldberg, and David Wagner.
- *
+ */
+/*
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -29,9 +28,8 @@
 /*! \addtogroup crypto
  *  @{
  *  Osmocom GSM/GPRS ciphering algorithm implementation
- */
-
-/*! \file gsm/a5.c */
+ *
+ * \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 287973b..c59ebb7 100644
--- a/src/gsm/abis_nm.c
+++ b/src/gsm/abis_nm.c
@@ -1,7 +1,5 @@
-/* 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 */
-
-/* (C) 2008-2011 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008-2011 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
@@ -22,11 +20,10 @@
 
 /*! \addtogroup oml
  *  @{
- * GSM Network Management (OML) messages on the A-bis interface
+ * 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 */
+ *
+ * \file abis_nm.c */
 
 #include <stdint.h>
 #include <errno.h>
diff --git a/src/gsm/apn.c b/src/gsm/apn.c
index ccf36b9..8d4b2bf 100644
--- a/src/gsm/apn.c
+++ b/src/gsm/apn.c
@@ -1,3 +1,5 @@
+/*! \file apn.c */
+
 #include <stdio.h>
 #include <stdint.h>
 #include <stdlib.h>
diff --git a/src/gsm/auth_comp128v1.c b/src/gsm/auth_comp128v1.c
index 3b645d2..1dddef3 100644
--- a/src/gsm/auth_comp128v1.c
+++ b/src/gsm/auth_comp128v1.c
@@ -1,7 +1,7 @@
-
-/* GSM/GPRS/3G authentication core infrastructure */
-
-/* (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
+/*! \file auth_comp128v1.c
+ * GSM/GPRS/3G authentication core infrastructure */
+/*
+ * (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/auth_comp128v23.c b/src/gsm/auth_comp128v23.c
index b0900af..4d23769 100644
--- a/src/gsm/auth_comp128v23.c
+++ b/src/gsm/auth_comp128v23.c
@@ -1,9 +1,8 @@
-/* registers COMP128 version 2 and 3 A3/A8 algorithms for the
- * GSM/GPRS/3G authentication core infrastructure
- *
- */
-
-/* (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
+/*! \file auth_comp128v23.c
+ * registers COMP128 version 2 and 3 A3/A8 algorithms for the
+ * GSM/GPRS/3G authentication core infrastructure. */
+/*
+ * (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
  * (C) 2013 by Kévin Redon <kevredon@mail.tsaitgaist.info>
  *
  * All Rights Reserved
diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c
index 1bdd4a8..4156695 100644
--- a/src/gsm/auth_core.c
+++ b/src/gsm/auth_core.c
@@ -1,5 +1,3 @@
-/* GSM/GPRS/3G authentication core infrastructure */
-
 /* (C) 2010-2012 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
@@ -33,9 +31,8 @@
 /*! \addtogroup auth
  *  @{
  *  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 41e538d..8d50990 100644
--- a/src/gsm/auth_milenage.c
+++ b/src/gsm/auth_milenage.c
@@ -1,6 +1,7 @@
-/* GSM/GPRS/3G authentication core infrastructure */
-
-/* (C) 2011 by Harald Welte <laforge@gnumonks.org>
+/*! \file auth_milenage.c
+ * GSM/GPRS/3G authentication core infrastructure */
+/*
+ * (C) 2011 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/comp128.c b/src/gsm/comp128.c
index 78f0e07..0fcc67d 100644
--- a/src/gsm/comp128.c
+++ b/src/gsm/comp128.c
@@ -1,6 +1,5 @@
-/*
- * COMP128 implementation
- *
+/*! \file comp128.c
+ *  COMP128 v1; common/old GSM Authentication Algorithm (A3/A8).
  *
  * This code is inspired by original code from :
  *  Marc Briceno <marc@scard.org>, Ian Goldberg <iang@cs.berkeley.edu>,
@@ -11,7 +10,38 @@
  * A comment snippet from the original code is included below, it describes
  * where the doc came from and how the algorithm was reverse engineered.
  *
+ * This code derived from a leaked document from the GSM standards.
+ * Some missing pieces were filled in by reverse-engineering a working SIM.
+ * We have verified that this is the correct COMP128 algorithm.
  *
+ * The first page of the document identifies it as
+ *
+ * 	_Technical Information: GSM System Security Study_.
+ * 	10-1617-01, 10th June 1988.
+ *
+ * The bottom of the title page is marked
+ *
+ * 	Racal Research Ltd.
+ * 	Worton Drive, Worton Grange Industrial Estate,
+ * 	Reading, Berks. RG2 0SB, England.
+ * 	Telephone: Reading (0734) 868601   Telex: 847152
+ *
+ * The relevant bits are in Part I, Section 20 (pages 66--67).  Enjoy!
+ *
+ * Note: There are three typos in the spec (discovered by
+ * reverse-engineering).
+ * - First, "z = (2 * x[n] + x[n]) mod 2^(9-j)" should clearly read
+ *   "z = (2 * x[m] + x[n]) mod 2^(9-j)".
+ * - Second, the "k" loop in the "Form bits from bytes" section is severely
+ *   botched: the k index should run only from 0 to 3, and clearly the range
+ *   on "the (8-k)th bit of byte j" is also off (should be 0..7, not 1..8,
+ *   to be consistent with the subsequent section).
+ * - Third, SRES is taken from the first 8 nibbles of x[], not the last 8 as
+ *   claimed in the document.  (And the document doesn't specify how Kc is
+ *   derived, but that was also easily discovered with reverse engineering.)
+ * All of these typos have been corrected in the following code.
+ */
+/*
  * (C) 2009 by Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -32,49 +62,12 @@
  *
  */
 
-/*
- * --- SNIP ---
- *
- * This code derived from a leaked document from the GSM standards.
- * Some missing pieces were filled in by reverse-engineering a working SIM.
- * We have verified that this is the correct COMP128 algorithm.
- *
- * The first page of the document identifies it as
- * 	_Technical Information: GSM System Security Study_.
- * 	10-1617-01, 10th June 1988.
- * The bottom of the title page is marked
- * 	Racal Research Ltd.
- * 	Worton Drive, Worton Grange Industrial Estate,
- * 	Reading, Berks. RG2 0SB, England.
- * 	Telephone: Reading (0734) 868601   Telex: 847152
- * The relevant bits are in Part I, Section 20 (pages 66--67).  Enjoy!
- *
- * Note: There are three typos in the spec (discovered by
- * reverse-engineering).
- * First, "z = (2 * x[n] + x[n]) mod 2^(9-j)" should clearly read
- * "z = (2 * x[m] + x[n]) mod 2^(9-j)".
- * Second, the "k" loop in the "Form bits from bytes" section is severely
- * botched: the k index should run only from 0 to 3, and clearly the range
- * on "the (8-k)th bit of byte j" is also off (should be 0..7, not 1..8,
- * to be consistent with the subsequent section).
- * Third, SRES is taken from the first 8 nibbles of x[], not the last 8 as
- * claimed in the document.  (And the document doesn't specify how Kc is
- * derived, but that was also easily discovered with reverse engineering.)
- * All of these typos have been corrected in the following code.
- *
- * --- /SNIP ---
- */
-
 #include <string.h>
 #include <stdint.h>
 
 /*! \addtogroup auth
  *  @{
- */
-
-/*! \file comp128.c
- *  COMP128 v1; common/old GSM Authentication Algorithm (A3/A8)
- */
+ * \file comp128.c */
 
 /* The compression tables (just copied ...) */
 static const uint8_t table_0[512] = {
diff --git a/src/gsm/comp128v23.c b/src/gsm/comp128v23.c
index 1797ebc..12f8a4c 100644
--- a/src/gsm/comp128v23.c
+++ b/src/gsm/comp128v23.c
@@ -1,11 +1,11 @@
-/* COMP128 version 2 and 3 implementation
+/*! \file comp128v23.c
+ * COMP128 version 2 and 3 implementation, common algorithm used for GSM Authentication (A3/A8).
  *
  * This code is a C conversion of the original code from
  * http://www.hackingprojects.net/
- *
  */
-
-/* (C) 2013 by Kévin Redon <kevredon@mail.tsaitgaist.info>
+/*
+ * (C) 2013 by Kévin Redon <kevredon@mail.tsaitgaist.info>
  *
  * All Rights Reserved
  *
@@ -30,11 +30,7 @@
 
 /*! \addtogroup auth
  *  @{
- */
-
-/*! \file comp128v23.c
- *  COMP128 v2 / v3; Common Algorithm used for GSM Authentication (A3/A8)
- */
+ * \file comp128v23.c */
 
 static const uint8_t table0[256] = {
 	197, 235, 60, 151, 98, 96, 3, 100, 248, 118, 42, 117, 172, 211, 181, 203, 61,
diff --git a/src/gsm/gan.c b/src/gsm/gan.c
index d357b7e..fae93f1 100644
--- a/src/gsm/gan.c
+++ b/src/gsm/gan.c
@@ -1,4 +1,7 @@
-/* (C) 2012 by Harald Welte <laforge@gnumonks.org>
+/*! \file gan.c
+ *  Generic Access Network (GAN) / UMA according to TS 44.318. */
+/*
+ * (C) 2012 by Harald Welte <laforge@gnumonks.org>
  * All Rights Reserved
  *
  * This program is free software; you can redistribute it and/or modify
@@ -21,11 +24,6 @@
 
 #include <osmocom/gsm/protocol/gsm_44_318.h>
 
-/*! \file gan.c
- *  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" },
 	{ GA_MT_RC_DISCOVERY_ACCEPT,	"GA-RC DISCOVERY ACCEPT" },
diff --git a/src/gsm/gea.c b/src/gsm/gea.c
index d4e599c..d95c03e 100644
--- a/src/gsm/gea.c
+++ b/src/gsm/gea.c
@@ -1,8 +1,6 @@
+/*! \file gea.c
+ * Implementation of GEA3 and GEA4. */
 /*
- * gea.c
- *
- * Implementation of GEA3 and GEA4
- *
  * Copyright (C) 2016 by Sysmocom s.f.m.c. GmbH
  *
  * All Rights Reserved
@@ -32,10 +30,7 @@
 
 /*! \addtogroup crypto
  *  @{
- */
-
-/*! \file gsm/gea.c */
-
+ * \file gsm/gea.c */
 
 /*! Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0
  *  \param[in,out] out Buffer for gamma for encrypted/decrypted
diff --git a/src/gsm/gprs_cipher_core.c b/src/gsm/gprs_cipher_core.c
index b833048..fc68c40 100644
--- a/src/gsm/gprs_cipher_core.c
+++ b/src/gsm/gprs_cipher_core.c
@@ -1,6 +1,7 @@
-/* GPRS LLC cipher core infrastructure */
-
-/* (C) 2010 by Harald Welte <laforge@gnumonks.org>
+/*! \file gprs_cipher_core.c
+ * GPRS LLC cipher core infrastructure */
+/*
+ * (C) 2010 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/gprs_gea.c b/src/gsm/gprs_gea.c
index 836ee68..db3f2cc 100644
--- a/src/gsm/gprs_gea.c
+++ b/src/gsm/gprs_gea.c
@@ -1,8 +1,6 @@
+/*! \file gprs_gea.c
+ * GEA 3 & 4 plugin */
 /*
- * gprs_gea.c
- *
- * GEA 3 & 4 plugin
- *
  * Copyright (C) 2016 by Sysmocom s.f.m.c. GmbH
  *
  * All Rights Reserved
diff --git a/src/gsm/gprs_rlc.c b/src/gsm/gprs_rlc.c
index 4b32947..b213b26 100644
--- a/src/gsm/gprs_rlc.c
+++ b/src/gsm/gprs_rlc.c
@@ -1,3 +1,7 @@
+/*! \file gsm/gprs_rlc.c
+ *  helper functions for (E)GPRS RLC according to 3GPP TS 44.060.
+ */
+
 #include <errno.h>
 #include <string.h>
 
@@ -5,10 +9,6 @@
 #include <osmocom/coding/gsm0503_coding.h>
 #include <osmocom/gprs/protocol/gsm_04_60.h>
 
-/*! \file gsm/gprs_rlc.c
- *  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 0e3e453..05a0b4a 100644
--- a/src/gsm/gsm0341.c
+++ b/src/gsm/gsm0341.c
@@ -1,3 +1,4 @@
+/*! \file gsm0341.c */
 /*
  * (C) 2014 by Harald Welte <laforge@gnumonks.org>
  * All Rights Reserved
diff --git a/src/gsm/gsm0411_smc.c b/src/gsm/gsm0411_smc.c
index dab83eb..7414e95 100644
--- a/src/gsm/gsm0411_smc.c
+++ b/src/gsm/gsm0411_smc.c
@@ -1,8 +1,9 @@
-/* Point-to-Point (PP) Short Message Service (SMS)
+/*! \file gsm0411_smc.c
+ * Point-to-Point (PP) Short Message Service (SMS).
  * Support on Mobile Radio Interface
- * 3GPP TS 04.11 version 7.1.0 Release 1998 / ETSI TS 100 942 V7.1.0 */
-
-/* (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
+ * 3GPP TS 04.11 version 7.1.0 Release 1998 / ETSI TS 100 942 V7.1.0. */
+/*
+ * (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
  * (C) 2009 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2010 by On-Waves
diff --git a/src/gsm/gsm0411_smr.c b/src/gsm/gsm0411_smr.c
index d120f2d..67bb249 100644
--- a/src/gsm/gsm0411_smr.c
+++ b/src/gsm/gsm0411_smr.c
@@ -1,8 +1,9 @@
-/* Point-to-Point (PP) Short Message Service (SMS)
+/*! \file gsm0411_smr.c
+ * Point-to-Point (PP) Short Message Service (SMS).
  * Support on Mobile Radio Interface
  * 3GPP TS 04.11 version 7.1.0 Release 1998 / ETSI TS 100 942 V7.1.0 */
-
-/* (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
+/*
+ * (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
  * (C) 2009 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2010 by On-Waves
diff --git a/src/gsm/gsm0411_utils.c b/src/gsm/gsm0411_utils.c
index ef67930..7c7164c 100644
--- a/src/gsm/gsm0411_utils.c
+++ b/src/gsm/gsm0411_utils.c
@@ -1,8 +1,9 @@
-/* Point-to-Point (PP) Short Message Service (SMS)
+/*! \file gsm0411_utils.c
+ * Point-to-Point (PP) Short Message Service (SMS).
  * Support on Mobile Radio Interface
- * 3GPP TS 04.11 version 7.1.0 Release 1998 / ETSI TS 100 942 V7.1.0 */
-
-/* (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
+ * 3GPP TS 04.11 version 7.1.0 Release 1998 / ETSI TS 100 942 V7.1.0. */
+/*
+ * (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
  * (C) 2009 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010-2013 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2010 by On-Waves
diff --git a/src/gsm/gsm0414.c b/src/gsm/gsm0414.c
index 84d393d..616d7d9 100644
--- a/src/gsm/gsm0414.c
+++ b/src/gsm/gsm0414.c
@@ -1,3 +1,5 @@
+/*! \file gsm0414.c */
+
 #include <osmocom/gsm/protocol/gsm_04_14.h>
 #include <osmocom/core/utils.h>
 
diff --git a/src/gsm/gsm0480.c b/src/gsm/gsm0480.c
index 3c23f6f..557aa14 100644
--- a/src/gsm/gsm0480.c
+++ b/src/gsm/gsm0480.c
@@ -1,5 +1,5 @@
-/* Format functions for GSM 04.80 */
-
+/*! \file gsm0480.c
+ * Format functions for GSM 04.80. */
 /*
  * (C) 2010 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2009 by Mike Haben <michael.haben@btinternet.com>
diff --git a/src/gsm/gsm0502.c b/src/gsm/gsm0502.c
index df1d8e9..6b69893 100644
--- a/src/gsm/gsm0502.c
+++ b/src/gsm/gsm0502.c
@@ -1,6 +1,7 @@
-/* Paging helper code */
-
-/* (C) 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
+/*! \file gsm0502.c
+ * Paging helper code */
+/*
+ * (C) 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
  * All Rights Reserved
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/gsm0808.c b/src/gsm/gsm0808.c
index f595dd6..a8a5e45 100644
--- a/src/gsm/gsm0808.c
+++ b/src/gsm/gsm0808.c
@@ -1,4 +1,6 @@
-/* (C) 2009,2010 by Holger Hans Peter Freyther <zecke@selfish.org>
+/*! \file gsm0808.c */
+/*
+ * (C) 2009,2010 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2009,2010 by On-Waves
  * All Rights Reserved
  *
diff --git a/src/gsm/gsm0808_utils.c b/src/gsm/gsm0808_utils.c
index 34e10bb..e2cd91b 100644
--- a/src/gsm/gsm0808_utils.c
+++ b/src/gsm/gsm0808_utils.c
@@ -1,4 +1,6 @@
-/* (C) 2016 by Sysmocom s.f.m.c. GmbH
+/*! \file gsm0808_utils.c */
+/*
+ * (C) 2016 by Sysmocom s.f.m.c. GmbH
  * All Rights Reserved
  *
  * Author: Philipp Maier
diff --git a/src/gsm/gsm48.c b/src/gsm/gsm48.c
index 227dbef..f69eee2 100644
--- a/src/gsm/gsm48.c
+++ b/src/gsm/gsm48.c
@@ -1,7 +1,8 @@
-/* GSM Mobile Radio Interface Layer 3 messages
+/*! \file gsm48.c
+ * GSM Mobile Radio Interface Layer 3 messages
  * 3GPP TS 04.08 version 7.21.0 Release 1998 / ETSI TS 100 940 V7.21.0 */
-
-/* (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
  * (C) 2008, 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
  *
  * All Rights Reserved
diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c
index d3a868d..105acba 100644
--- a/src/gsm/gsm48_ie.c
+++ b/src/gsm/gsm48_ie.c
@@ -1,7 +1,8 @@
-/* GSM Mobile Radio Interface Layer 3 messages
- * 3GPP TS 04.08 version 7.21.0 Release 1998 / ETSI TS 100 940 V7.21.0 */
-
-/* (C) 2008 by Harald Welte <laforge@gnumonks.org>
+/*! \file gsm48_ie.c
+ * GSM Mobile Radio Interface Layer 3 messages.
+ * 3GPP TS 04.08 version 7.21.0 Release 1998 / ETSI TS 100 940 V7.21.0. */
+/*
+ * (C) 2008 by Harald Welte <laforge@gnumonks.org>
  * (C) 2009-2010 by Andreas Eversberg
  *
  * All Rights Reserved
diff --git a/src/gsm/gsm_04_08_gprs.c b/src/gsm/gsm_04_08_gprs.c
index 7bcef4e..43da27e 100644
--- a/src/gsm/gsm_04_08_gprs.c
+++ b/src/gsm/gsm_04_08_gprs.c
@@ -1,4 +1,6 @@
-/* (C) 2009-2016 by Harald Welte <laforge@gnumonks.org>
+/*! \file gsm_04_08_gprs.c */
+/*
+ * (C) 2009-2016 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010      by On-Waves
  * (C) 2014-2015 by Sysmocom s.f.m.c. GmbH
  *
diff --git a/src/gsm/gsm_utils.c b/src/gsm/gsm_utils.c
index fd16e98..5a4ceb3 100644
--- a/src/gsm/gsm_utils.c
+++ b/src/gsm/gsm_utils.c
@@ -1,3 +1,4 @@
+/*! \file gsm_utils.c */
 /*
  * (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
  * (C) 2009,2013 by Holger Hans Peter Freyther <zecke@selfish.org>
diff --git a/src/gsm/gsup.c b/src/gsm/gsup.c
index 780198c..2629eb7 100644
--- a/src/gsm/gsup.c
+++ b/src/gsm/gsup.c
@@ -1,5 +1,5 @@
-/* Osmocom Generic Subscriber Update Protocol message encoder/decoder */
-
+/*! \file gsup.c
+ * Osmocom Generic Subscriber Update Protocol message encoder/decoder. */
 /*
  * (C) 2014 by sysmocom s.f.m.c. GmbH
  * (C) 2015 by Holger Hans Peter Freyther
diff --git a/src/gsm/ipa.c b/src/gsm/ipa.c
index 2c7cf58..bc84850 100644
--- a/src/gsm/ipa.c
+++ b/src/gsm/ipa.c
@@ -1,6 +1,7 @@
-/* OpenBSC Abis input driver for ip.access */
-
-/* (C) 2009-2017 by Harald Welte <laforge@gnumonks.org>
+/*! \file ipa.c
+ * OpenBSC Abis input driver for ip.access */
+/*
+ * (C) 2009-2017 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010 by Holger Hans Peter Freyther
  * (C) 2010 by On-Waves
  *
diff --git a/src/gsm/kasumi.c b/src/gsm/kasumi.c
index d5d78a7..c3a028b 100644
--- a/src/gsm/kasumi.c
+++ b/src/gsm/kasumi.c
@@ -1,6 +1,7 @@
-/* Kasumi cipher and KGcore functions */
-
-/* (C) 2013 by Max <Max.Suraev@fairwaves.ru>
+/*! \file kasumi.c
+ * Kasumi cipher and KGcore functions. */
+/*
+ * (C) 2013 by Max <Max.Suraev@fairwaves.ru>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/lapd_core.c b/src/gsm/lapd_core.c
index 4ad7556..166bf9a 100644
--- a/src/gsm/lapd_core.c
+++ b/src/gsm/lapd_core.c
@@ -1,6 +1,7 @@
-/* LAPD core implementation */
-
-/* (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
+/*! \file lapd_core.c
+ * LAPD core implementation */
+/*
+ * (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010-2011 by Andreas Eversberg <jolly@eversberg.eu>
  *
  * All Rights Reserved
@@ -23,12 +24,9 @@
 
 /*! \addtogroup lapd
  *  @{
- *  Osmocom LAPD core, used for Q.921, LAPDm and others
- */
-
-/*! \file lapd_core.c */
-
-/*!
+ *
+ * Osmocom LAPD core, used for Q.921, LAPDm and others.
+ *
  * Notes on Buffering: rcv_buffer, tx_queue, tx_hist, send_buffer, send_queue
  *
  * RX data is stored in the rcv_buffer (pointer). If the message is complete, it
@@ -62,6 +60,7 @@
  * will not trigger T200. It will be stoped, when T200 is started in MF EST
  * state. It will also be stoped when leaving MF EST state.
  *
+ * \file lapd_core.c
  */
 
 /* Enable this to test content resolution on network side:
diff --git a/src/gsm/lapdm.c b/src/gsm/lapdm.c
index 1152e0d..db950a6 100644
--- a/src/gsm/lapdm.c
+++ b/src/gsm/lapdm.c
@@ -1,6 +1,7 @@
-/* GSM LAPDm (TS 04.06) implementation */
-
-/* (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
+/*! \file lapdm.c
+ * GSM LAPDm (TS 04.06) implementation. */
+/*
+ * (C) 2010-2011 by Harald Welte <laforge@gnumonks.org>
  * (C) 2010-2011 by Andreas Eversberg <jolly@eversberg.eu>
  *
  * All Rights Reserved
@@ -23,10 +24,7 @@
 
 /*! \addtogroup lapdm
  *  @{
- *  GSM LAPDm (TS 04.06) implementation
- */
-
-/*! \file lapdm.c */
+ * \file lapdm.c */
 
 #include <stdio.h>
 #include <stdint.h>
diff --git a/src/gsm/milenage/aes-encblock.c b/src/gsm/milenage/aes-encblock.c
index 8f35caa..c4aa260 100644
--- a/src/gsm/milenage/aes-encblock.c
+++ b/src/gsm/milenage/aes-encblock.c
@@ -1,6 +1,6 @@
+/*! \file aes-encblock.c
+ * AES encrypt_block. */
 /*
- * AES encrypt_block
- *
  * Copyright (c) 2003-2007, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/aes-internal-enc.c b/src/gsm/milenage/aes-internal-enc.c
index 8726aa7..4c00f96 100644
--- a/src/gsm/milenage/aes-internal-enc.c
+++ b/src/gsm/milenage/aes-internal-enc.c
@@ -1,5 +1,5 @@
-/*
- * AES (Rijndael) cipher - encrypt
+/*! \file aes-internal-enc.c
+ * AES (Rijndael) cipher - encrypt.
  *
  * Modifications to public domain implementation:
  * - support only 128-bit keys
@@ -8,7 +8,8 @@
  * - added option (AES_SMALL_TABLES) for reducing code size by about 8 kB at
  *   cost of reduced throughput (quite small difference on Pentium 4,
  *   10-25% when using -O1 or -O2 optimization)
- *
+ */
+/*
  * Copyright (c) 2003-2005, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/aes-internal.c b/src/gsm/milenage/aes-internal.c
index 4161220..60c520c 100644
--- a/src/gsm/milenage/aes-internal.c
+++ b/src/gsm/milenage/aes-internal.c
@@ -1,5 +1,5 @@
-/*
- * AES (Rijndael) cipher
+/*! \file aes-internal.c
+ * AES (Rijndael) cipher.
  *
  * Modifications to public domain implementation:
  * - support only 128-bit keys
@@ -8,7 +8,8 @@
  * - added option (AES_SMALL_TABLES) for reducing code size by about 8 kB at
  *   cost of reduced throughput (quite small difference on Pentium 4,
  *   10-25% when using -O1 or -O2 optimization)
- *
+ */
+/*
  * Copyright (c) 2003-2005, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/aes.h b/src/gsm/milenage/aes.h
index 7e97f61..ce42b20 100644
--- a/src/gsm/milenage/aes.h
+++ b/src/gsm/milenage/aes.h
@@ -1,5 +1,6 @@
+/*! \file aes.h
+ * AES functions */
 /*
- * AES functions
  * Copyright (c) 2003-2006, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/aes_i.h b/src/gsm/milenage/aes_i.h
index 5d89abc..6df019a 100644
--- a/src/gsm/milenage/aes_i.h
+++ b/src/gsm/milenage/aes_i.h
@@ -1,5 +1,6 @@
+/*! \file aes_i.h
+ * AES (Rijndael) cipher. */
 /*
- * AES (Rijndael) cipher
  * Copyright (c) 2003-2005, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/aes_wrap.h b/src/gsm/milenage/aes_wrap.h
index afa1451..7d4d5d9 100644
--- a/src/gsm/milenage/aes_wrap.h
+++ b/src/gsm/milenage/aes_wrap.h
@@ -1,12 +1,13 @@
-/*
- * AES-based functions
+/*! \file aes_wrap.h
+ * AES-based functions.
  *
  * - AES Key Wrap Algorithm (128-bit KEK) (RFC3394)
  * - One-Key CBC MAC (OMAC1) hash with AES-128
  * - AES-128 CTR mode encryption
  * - AES-128 EAX mode encryption/decryption
  * - AES-128 CBC
- *
+ */
+/*
  * Copyright (c) 2003-2007, Jouni Malinen <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/common.h b/src/gsm/milenage/common.h
index aaf82b9..2aa50fb 100644
--- a/src/gsm/milenage/common.h
+++ b/src/gsm/milenage/common.h
@@ -1,3 +1,4 @@
+/*! \file common.h */
 
 #include <stdint.h>
 #include <stdlib.h>
diff --git a/src/gsm/milenage/milenage.c b/src/gsm/milenage/milenage.c
index b43f986..012b399 100644
--- a/src/gsm/milenage/milenage.c
+++ b/src/gsm/milenage/milenage.c
@@ -1,5 +1,6 @@
+/*! \file milenage.c
+ * 3GPP AKA - Milenage algorithm (3GPP TS 35.205, .206, .207, .208) */
 /*
- * 3GPP AKA - Milenage algorithm (3GPP TS 35.205, .206, .207, .208)
  * Copyright (c) 2006-2007 <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/milenage/milenage.h b/src/gsm/milenage/milenage.h
index 6fb779c..1a4364d 100644
--- a/src/gsm/milenage/milenage.h
+++ b/src/gsm/milenage/milenage.h
@@ -1,5 +1,7 @@
+/*! \file milenage.h
+ * UMTS AKA - Milenage algorithm (3GPP TS 35.205, .206, .207, .208).
+ */
 /*
- * UMTS AKA - Milenage algorithm (3GPP TS 35.205, .206, .207, .208)
  * Copyright (c) 2006-2007 <j@w1.fi>
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/gsm/oap.c b/src/gsm/oap.c
index 88c98f7..b07eafc 100644
--- a/src/gsm/oap.c
+++ b/src/gsm/oap.c
@@ -1,6 +1,7 @@
-/* Osmocom Authentication Protocol message encoder/decoder */
-
-/* (C) 2015-2016 by sysmocom s.f.m.c. GmbH
+/*! \file oap.c
+ * Osmocom Authentication Protocol message encoder/decoder */
+/*
+ * (C) 2015-2016 by sysmocom s.f.m.c. GmbH
  * All Rights Reserved
  *
  * Author: Neels Hofmeyr
diff --git a/src/gsm/rsl.c b/src/gsm/rsl.c
index 4a1f733..e33ea10 100644
--- a/src/gsm/rsl.c
+++ b/src/gsm/rsl.c
@@ -1,7 +1,5 @@
-/* GSM Radio Signalling Link messages on the A-bis interface 
- * 3GPP TS 08.58 version 8.6.0 Release 1999 / ETSI TS 100 596 V8.6.0 */
-
-/* (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
@@ -30,10 +28,10 @@
 
 /*! \addtogroup rsl
  *  @{
- *  GSM Radio Signalling Link (TS 08.58)
- */
-
-/*! \file rsl.c */
+ * GSM Radio Signalling Link messages on the A-bis interface.
+ * 3GPP TS 08.58 version 8.6.0 Release 1999 / ETSI TS 100 596 V8.6.0.
+ *
+ * \file rsl.c */
 
 /*! Size for RSL \ref msgb_alloc */
 #define RSL_ALLOC_SIZE		200
diff --git a/src/gsm/rxlev_stat.c b/src/gsm/rxlev_stat.c
index d226861..2ff0ac8 100644
--- a/src/gsm/rxlev_stat.c
+++ b/src/gsm/rxlev_stat.c
@@ -1,6 +1,7 @@
-/* Rx Level statistics */
-
-/* (C) 2010 by Harald Welte <laforge@gnumonks.org>
+/*! \file rxlev_stat.c
+ * Rx Level statistics */
+/*
+ * (C) 2010 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/sysinfo.c b/src/gsm/sysinfo.c
index 201acfc..b73bb0c 100644
--- a/src/gsm/sysinfo.c
+++ b/src/gsm/sysinfo.c
@@ -1,7 +1,8 @@
-/* GSM 04.08 System Information (SI) encoding and decoding
+/*! \file sysinfo.c
+ * GSM 04.08 System Information (SI) encoding and decoding.
  * 3GPP TS 04.08 version 7.21.0 Release 1998 / ETSI TS 100 940 V7.21.0 */
-
-/* (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008-2010 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
diff --git a/src/gsm/tlv_parser.c b/src/gsm/tlv_parser.c
index d9072c9..b1b1034 100644
--- a/src/gsm/tlv_parser.c
+++ b/src/gsm/tlv_parser.c
@@ -39,9 +39,8 @@
  *  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 */
+ *
+ * \file tlv_parser.c */
 
 struct tlv_definition tvlv_att_def;
 struct tlv_definition vtvlv_gan_att_def;