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/include/osmocom/gsm/protocol/gsm_03_40.h b/include/osmocom/gsm/protocol/gsm_03_40.h
index 32d5c2c..a65203f 100644
--- a/include/osmocom/gsm/protocol/gsm_03_40.h
+++ b/include/osmocom/gsm/protocol/gsm_03_40.h
@@ -1,6 +1,7 @@
-#pragma once
+/*! \file gsm_03_40.h
+ * GSM TS 03.40. */
-/* GSM TS 03.40 */
+#pragma once
/**
* 9.1.2.5 Type Of Number
diff --git a/include/osmocom/gsm/protocol/gsm_03_41.h b/include/osmocom/gsm/protocol/gsm_03_41.h
index 40051cd..2e0ad69 100644
--- a/include/osmocom/gsm/protocol/gsm_03_41.h
+++ b/include/osmocom/gsm/protocol/gsm_03_41.h
@@ -1,3 +1,6 @@
+/*! \file gsm_03_41.h
+ * GSM TS 03.41 definitions also TS 23.041. */
+
#pragma once
#include <stdint.h>
@@ -9,8 +12,6 @@
#define OSMO_IS_LITTLE_ENDIAN 0
#endif
-/* GSM TS 03.41 definitions also TS 23.041*/
-
#define GSM341_MAX_PAYLOAD (GSM412_MSG_LEN-sizeof(struct gsm341_ms_message))
#define GSM341_MAX_CHARS (GSM341_MAX_PAYLOAD*8/7)
#define GSM341_7BIT_PADDING '\r'
diff --git a/include/osmocom/gsm/protocol/gsm_04_08.h b/include/osmocom/gsm/protocol/gsm_04_08.h
index 90b6cf1..643f046 100644
--- a/include/osmocom/gsm/protocol/gsm_04_08.h
+++ b/include/osmocom/gsm/protocol/gsm_04_08.h
@@ -1,3 +1,6 @@
+/*! \file gsm_04_08.h
+ * GSM TS 04.08 definitions. */
+
#pragma once
#include <stdint.h>
@@ -6,7 +9,6 @@
#include <osmocom/core/utils.h>
#include <osmocom/core/endian.h>
-/* GSM TS 04.08 definitions */
struct gsm_lchan;
/* Chapter 10.5.1.5 */
diff --git a/include/osmocom/gsm/protocol/gsm_04_08_gprs.h b/include/osmocom/gsm/protocol/gsm_04_08_gprs.h
index def8dfc..13820a7 100644
--- a/include/osmocom/gsm/protocol/gsm_04_08_gprs.h
+++ b/include/osmocom/gsm/protocol/gsm_04_08_gprs.h
@@ -1,3 +1,5 @@
+/*! \file gsm_04_08_gprs.h */
+
#ifndef _GSM48_GPRS_H
#define _GSM48_GPRS_H
diff --git a/include/osmocom/gsm/protocol/gsm_04_11.h b/include/osmocom/gsm/protocol/gsm_04_11.h
index 651adca..31f25ac 100644
--- a/include/osmocom/gsm/protocol/gsm_04_11.h
+++ b/include/osmocom/gsm/protocol/gsm_04_11.h
@@ -1,3 +1,5 @@
+/*! \file gsm_04_11.h */
+
#pragma once
#include <stdint.h>
diff --git a/include/osmocom/gsm/protocol/gsm_04_12.h b/include/osmocom/gsm/protocol/gsm_04_12.h
index 30d6e4f..826e69b 100644
--- a/include/osmocom/gsm/protocol/gsm_04_12.h
+++ b/include/osmocom/gsm/protocol/gsm_04_12.h
@@ -1,9 +1,10 @@
+/*! \file gsm_04_12.h
+ * GSM TS 04.12 definitions for Short Message Service Cell Broadcast. */
+
#pragma once
#include <stdint.h>
-/* GSM TS 04.12 definitions for Short Message Service Cell Broadcast */
-
#define GSM412_MSG_LEN 88 /* TS 04.12 Section 3.1 */
#define GSM412_BLOCK_LEN 22 /* TS 04.12 Section 3.1 */
diff --git a/include/osmocom/gsm/protocol/gsm_04_14.h b/include/osmocom/gsm/protocol/gsm_04_14.h
index 421b56f..6f7d92c 100644
--- a/include/osmocom/gsm/protocol/gsm_04_14.h
+++ b/include/osmocom/gsm/protocol/gsm_04_14.h
@@ -1,3 +1,5 @@
+/*! \file gsm_04_14.h */
+
#pragma once
#include <stdint.h>
diff --git a/include/osmocom/gsm/protocol/gsm_04_80.h b/include/osmocom/gsm/protocol/gsm_04_80.h
index 2aebb46..e204c50 100644
--- a/include/osmocom/gsm/protocol/gsm_04_80.h
+++ b/include/osmocom/gsm/protocol/gsm_04_80.h
@@ -1,6 +1,7 @@
-#pragma once
+/*! \file gsm_04_80.h
+ * GSM TS 04.80 definitions (Supplementary Services Specification, Formats and Coding). */
-/* GSM TS 04.80 definitions (Supplementary Services Specification, Formats and Coding) */
+#pragma once
/* Section 3.4 */
#define GSM0480_MTYPE_RELEASE_COMPLETE 0x2A
diff --git a/include/osmocom/gsm/protocol/gsm_08_58.h b/include/osmocom/gsm/protocol/gsm_08_58.h
index c76cf3b..bc70b93 100644
--- a/include/osmocom/gsm/protocol/gsm_08_58.h
+++ b/include/osmocom/gsm/protocol/gsm_08_58.h
@@ -1,9 +1,8 @@
-#pragma once
-
-/* GSM Radio Signalling Link messages on the A-bis interface
+/*! \file gsm_08_58.h
+ * 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 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008 by Harald Welte <laforge@gnumonks.org>
* All Rights Reserved
*
* This program is free software; you can redistribute it and/or modify
@@ -22,13 +21,13 @@
*
*/
+#pragma once
+
#include <stdint.h>
/*! \addtogroup rsl
* @{
- */
-
-/*! \file gsm_08_58.h */
+ * \file gsm_08_58.h */
/*! RSL common header */
struct abis_rsl_common_hdr {
diff --git a/include/osmocom/gsm/protocol/gsm_09_02.h b/include/osmocom/gsm/protocol/gsm_09_02.h
index 3f68b45..0b54fb7 100644
--- a/include/osmocom/gsm/protocol/gsm_09_02.h
+++ b/include/osmocom/gsm/protocol/gsm_09_02.h
@@ -1,8 +1,9 @@
+/*! \file gsm_09_02.h
+ * GSM TS 09.02 definitions (MAP). */
+
#ifndef PROTO_GSM_09_02_H
#define PROTO_GSM_09_02_H
-/* GSM TS 09.02 definitions (MAP) */
-
/* Section 17.7.4 */
/* SS-Status */
#define GSM0902_SS_STATUS_Q_BIT 0x08
diff --git a/include/osmocom/gsm/protocol/gsm_12_21.h b/include/osmocom/gsm/protocol/gsm_12_21.h
index 1bdee9c..3ef3603 100644
--- a/include/osmocom/gsm/protocol/gsm_12_21.h
+++ b/include/osmocom/gsm/protocol/gsm_12_21.h
@@ -1,9 +1,5 @@
-#pragma once
-
-/* GSM Network Management 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-2009 by Harald Welte <laforge@gnumonks.org>
+/*
+ * (C) 2008-2009 by Harald Welte <laforge@gnumonks.org>
* All Rights Reserved
*
* This program is free software; you can redistribute it and/or modify
@@ -22,11 +18,11 @@
*
*/
+#pragma once
+
/*! \addtogroup oml
* @{
- */
-
-/*! \file gsm_12_21.h */
+ * \file gsm_12_21.h */
#include <stdint.h>
#include <stdbool.h>
diff --git a/include/osmocom/gsm/protocol/gsm_23_003.h b/include/osmocom/gsm/protocol/gsm_23_003.h
index a2109b6..94243fe 100644
--- a/include/osmocom/gsm/protocol/gsm_23_003.h
+++ b/include/osmocom/gsm/protocol/gsm_23_003.h
@@ -1,3 +1,5 @@
+/*! \file gsm_23_003.h */
+
#pragma once
/* Chapter 2.2 */
diff --git a/include/osmocom/gsm/protocol/gsm_44_318.h b/include/osmocom/gsm/protocol/gsm_44_318.h
index 5d7f878..76e8396 100644
--- a/include/osmocom/gsm/protocol/gsm_44_318.h
+++ b/include/osmocom/gsm/protocol/gsm_44_318.h
@@ -1,9 +1,10 @@
+/*! \file gsm_44_318.h
+ * Definitions according to 3GPP TS 44.318 6.8.0 Release 6. */
+
#pragma once
#include <stdint.h>
-/* Definitions according to 3GPP TS 44.318 6.8.0 Release 6 */
-
/* Table 11.1.1.2.1: Protocol Discriminator */
enum gan_pdisc {
GA_PDISC_RC = 0,
diff --git a/include/osmocom/gsm/protocol/ipaccess.h b/include/osmocom/gsm/protocol/ipaccess.h
index ba6cb3b..0f5d54f 100644
--- a/include/osmocom/gsm/protocol/ipaccess.h
+++ b/include/osmocom/gsm/protocol/ipaccess.h
@@ -1,3 +1,5 @@
+/*! \file ipaccess.h */
+
#pragma once
#include <stdint.h>
diff --git a/include/osmocom/gsm/protocol/smpp34_osmocom.h b/include/osmocom/gsm/protocol/smpp34_osmocom.h
index cff6adb..7c72ac8 100644
--- a/include/osmocom/gsm/protocol/smpp34_osmocom.h
+++ b/include/osmocom/gsm/protocol/smpp34_osmocom.h
@@ -1,5 +1,7 @@
+/*! \file smpp34_osmocom.h
+ * Osmocom SMPP extensions. */
+
#pragma once
-/* Osmocom SMPP extensions */
/* Osmocom specific new TLV definitions */