doxygen: unify use of \file across the board

Considering the various styles and implications found in the sources, edit
scores of files to follow the same API doc guidelines around the doxygen
grouping and the \file tag.

Many files now show a short description in the generated API doc that was so
far only available as C comment.

The guidelines and reasoning behind it is documented at
https://osmocom.org/projects/cellular-infrastructure/wiki/Guidelines_for_API_documentation

In some instances, remove file comments and add to the corresponding group
instead, to be shared among several files (e.g. bitvec).

Change-Id: Ifa70e77e90462b5eb2b0457c70fd25275910c72b

46 files changed, 193 insertions, 194 deletions

diff --git a/src/gsm/a5.c b/src/gsm/a5.c
index f21554f0..e906b6d9 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 287973b3..c59ebb7c 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 ccf36b99..8d4b2bfc 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 3b645d2a..1dddef31 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 b0900af2..4d23769c 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 1bdd4a84..41566959 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 41e538d2..8d50990b 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 78f0e07c..0fcc67d5 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 1797ebc9..12f8a4c1 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 d357b7e1..fae93f11 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 d4e599c8..d95c03e8 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 b833048d..fc68c402 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 836ee68c..db3f2cc7 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 4b329473..b213b269 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 0e3e453d..05a0b4a8 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 dab83ebd..7414e95a 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 d120f2df..67bb2494 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 ef679304..7c7164c9 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 84d393df..616d7d96 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 3c23f6fc..557aa148 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 df1d8e9e..6b698938 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 f595dd65..a8a5e45a 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 34e10bbc..e2cd91b4 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 227dbef8..f69eee20 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 d3a868d1..105acbaf 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 7bcef4ec..43da27ee 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 fd16e980..5a4ceb36 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 780198c3..2629eb75 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 2c7cf582..bc848504 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 d5d78a74..c3a028b7 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 4ad75568..166bf9a7 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
i