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

15 files changed, 46 insertions, 31 deletions

diff --git a/include/osmocom/gsm/protocol/gsm_03_40.h b/include/osmocom/gsm/protocol/gsm_03_40.h
index 32d5c2c2..a65203f9 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 40051cd4..2e0ad69f 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 90b6cf15..643f0464 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 def8dfcd..13820a78 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 651adcaa..31f25acb 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 30d6e4fa..826e69bd 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 421b56f1..6f7d92c9 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 2aebb46e..e204c50d 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 c76cf3b1..bc70b930 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 3f68b457..0b54fb74 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 1bdee9cd..3ef36038 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 a2109b60..94243feb 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 5d7f8787..76e8396c 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 ba6cb3be..0f5d54f2 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 cff6adba..7c72ac84 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 */