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
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;