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

119 files changed, 335 insertions, 309 deletions

diff --git a/include/osmocom/codec/codec.h b/include/osmocom/codec/codec.h
index 3e9b6881..3e62a013 100644
--- a/include/osmocom/codec/codec.h
+++ b/include/osmocom/codec/codec.h
@@ -1,3 +1,5 @@
+/*! \file codec.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/coding/gsm0503_coding.h b/include/osmocom/coding/gsm0503_coding.h
index a9c59e47..a2d4115b 100644
--- a/include/osmocom/coding/gsm0503_coding.h
+++ b/include/osmocom/coding/gsm0503_coding.h
@@ -1,3 +1,7 @@
+/*! \file gsm0503_coding.h
+ *  GSM TS 05.03 coding
+ */
+
 #pragma once
 
 #include <stdint.h>
@@ -5,11 +9,7 @@
 
 /*! \addtogroup coding
  *  @{
- */
-
-/*! \file gsm0503_coding.h
- *  GSM TS 05.03 coding
- */
+ * \file gsm0503_coding.h */
 
 #define GSM0503_GPRS_BURSTS_NBITS	(116 * 4)
 #define GSM0503_EGPRS_BURSTS_NBITS	(348 * 4)
diff --git a/include/osmocom/coding/gsm0503_interleaving.h b/include/osmocom/coding/gsm0503_interleaving.h
index 1463fb38..05b5e278 100644
--- a/include/osmocom/coding/gsm0503_interleaving.h
+++ b/include/osmocom/coding/gsm0503_interleaving.h
@@ -1,14 +1,14 @@
+/*! \file gsm0503_interleaving.h
+ *  GSM TS 05.03 interleaving.
+ */
+
 #pragma once
 
 #include <osmocom/core/bits.h>
 
 /*! \addtogroup interleaving
  *  @{
- */
-
-/*! \file gsm0503_interleaving.h
- *  GSM TS 05.03 interleaving
- */
+ * \file gsm0503_interleaving.h */
 
 void gsm0503_xcch_deinterleave(sbit_t *cB, const sbit_t *iB);
 void gsm0503_xcch_interleave(const ubit_t *cB, ubit_t *iB);
diff --git a/include/osmocom/coding/gsm0503_mapping.h b/include/osmocom/coding/gsm0503_mapping.h
index 435c9131..fbd3bfd7 100644
--- a/include/osmocom/coding/gsm0503_mapping.h
+++ b/include/osmocom/coding/gsm0503_mapping.h
@@ -1,14 +1,14 @@
+/*! \file gsm0503_mapping.c
+ *  GSM TS 05.03 burst mapping.
+ */
+
 #pragma once
 
 #include <osmocom/core/bits.h>
 
 /*! \addtogroup mapping
  *  @{
- */
-
-/*! \file gsm0503_mapping.c
- *  GSM TS 05.03 burst mapping
- */
+ * \file gsm0503_mapping.h */
 
 void gsm0503_xcch_burst_unmap(sbit_t *iB, const sbit_t *eB,
 	sbit_t *hl, sbit_t *hn);
diff --git a/include/osmocom/coding/gsm0503_parity.h b/include/osmocom/coding/gsm0503_parity.h
index 2743bdb1..28a54443 100644
--- a/include/osmocom/coding/gsm0503_parity.h
+++ b/include/osmocom/coding/gsm0503_parity.h
@@ -1,14 +1,14 @@
+/*! \file gsm0503_parity.h
+ *  GSM TS 05.03 parity.
+ */
+
 #pragma once
 
 #include <osmocom/core/crcgen.h>
 
 /*! \addtogroup parity
  *  @{
- */
-
-/*! \file gsm0503_parity.h
- *  GSM TS 05.03 parity
- */
+ * \file gsm0503_parity.h */
 
 const struct osmo_crc64gen_code gsm0503_fire_crc40;
 const struct osmo_crc16gen_code gsm0503_cs234_crc16;
diff --git a/include/osmocom/coding/gsm0503_tables.h b/include/osmocom/coding/gsm0503_tables.h
index f8c43c61..55c4ebec 100644
--- a/include/osmocom/coding/gsm0503_tables.h
+++ b/include/osmocom/coding/gsm0503_tables.h
@@ -1,3 +1,7 @@
+/*! \file gsm0503_tables.h
+ *  GSM TS 05.03 tables.
+ */
+
 #pragma once
 
 #include <stdint.h>
@@ -5,11 +9,7 @@
 
 /*! \addtogroup tables
  *  @{
- */
-
-/*! \file gsm0503_tables.h
- *  GSM TS 05.03 tables
- */
+ * \file gsm0503_tables.h */
 
 extern const ubit_t gsm0503_pdtch_hl_hn_ubit[4][8];
 extern const ubit_t gsm0503_pdtch_edge_hl_hn_ubit[3][8];
diff --git a/include/osmocom/core/backtrace.h b/include/osmocom/core/backtrace.h
index 0c9b6ef9..d661dd06 100644
--- a/include/osmocom/core/backtrace.h
+++ b/include/osmocom/core/backtrace.h
@@ -1,3 +1,5 @@
+/*! \file backtrace.h */
+
 #pragma once
 
 void osmo_generate_backtrace(void);
diff --git a/include/osmocom/core/bitcomp.h b/include/osmocom/core/bitcomp.h
index a184a1cf..dc356bd8 100644
--- a/include/osmocom/core/bitcomp.h
+++ b/include/osmocom/core/bitcomp.h
@@ -1,8 +1,7 @@
-#pragma once
-
-/* bit compression routines */
-
-/* (C) 2016 sysmocom s.f.m.c. GmbH by Max Suraev <msuraev@sysmocom.de>
+/*! \file bitcomp.h
+ *  Osmocom bit compression routines. */
+/*
+ * (C) 2016 sysmocom s.f.m.c. GmbH by Max Suraev <msuraev@sysmocom.de>
  *
  * All Rights Reserved
  *
@@ -22,13 +21,11 @@
  *
  */
 
+#pragma once
+
 /*! \defgroup bitcomp Bit compression
  *  @{
- */
-
-/*! \file bitcomp.h
- *  Osmocom bit compression routines
- */
+ * \file bitcomp.h */
 
 #include <stdint.h>
 #include <stdbool.h>
diff --git a/include/osmocom/core/bits.h b/include/osmocom/core/bits.h
index 61af716c..17fe1c6a 100644
--- a/include/osmocom/core/bits.h
+++ b/include/osmocom/core/bits.h
@@ -1,3 +1,11 @@
+/*! \file bits.h
+ *  Osmocom bit level support code.
+ *
+ *  NOTE on the endianess of pbit_t:
+ *  Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
+ *  Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
+ */
+
 #pragma once
 
 #include <stdint.h>
@@ -9,15 +17,7 @@
 
 /*! \defgroup bits soft, unpacked and packed bits
  *  @{
- */
-
-/*! \file bits.h
- *  Osmocom bit level support code
- *
- *  NOTE on the endianess of pbit_t:
- *  Bits in a pbit_t are ordered MSB first, i.e. 0x80 is the first bit.
- *  Bit i in a pbit_t array is array[i/8] & (1<<(7-i%8))
- */
+ * \file bits.h */
 
 typedef int8_t  sbit_t;		/*!< soft bit (-127...127) */
 typedef uint8_t ubit_t;		/*!< unpacked bit (0 or 1) */
diff --git a/include/osmocom/core/bitvec.h b/include/osmocom/core/bitvec.h
index 9187ce23..d4c7d680 100644
--- a/include/osmocom/core/bitvec.h
+++ b/include/osmocom/core/bitvec.h
@@ -1,7 +1,3 @@
-#pragma once
-
-/* bit vector utility routines */
-
 /* (C) 2009 by Harald Welte <laforge@gnumonks.org>
  * (C) 2012 Ivan Klyuchnikov
  * (C) 2015 Sysmocom s.f.m.c. GmbH
@@ -24,21 +20,11 @@
  *
  */
 
+#pragma once
+
 /*! \defgroup bitvec Bit vectors
  *  @{
- */
-
-/*! \file bitvec.h
- *  Osmocom bit vector abstraction
- *
- *  These functions assume a MSB (most significant bit) first layout of the
- *  bits, so that for instance the 5 bit number abcde (a is MSB) can be
- *  embedded into a byte sequence like in xxxxxxab cdexxxxx. The bit count
- *  starts with the MSB, so the bits in a byte are numbered (MSB) 01234567 (LSB).
- *  Note that there are other incompatible encodings, like it is used
- *  for the EGPRS RLC data block headers (there the bits are numbered from LSB
- *  to MSB).
- */
+ * \file bitvec.h */
 
 #include <stdint.h>
 #include <osmocom/core/talloc.h>
diff --git a/include/osmocom/core/byteswap.h b/include/osmocom/core/byteswap.h
index 4274b8fb..1ea5b3db 100644
--- a/include/osmocom/core/byteswap.h
+++ b/include/osmocom/core/byteswap.h
@@ -1,3 +1,5 @@
+/*! \file byteswap.h */
+
 #pragma once
 #include <stdint.h>
 #include <osmocom/core/endian.h>
diff --git a/include/osmocom/core/conv.h b/include/osmocom/core/conv.h
index 1888fe13..8b344f4d 100644
--- a/include/osmocom/core/conv.h
+++ b/include/osmocom/core/conv.h
@@ -1,6 +1,6 @@
+/*! \file conv.h
+ * Osmocom convolutional encoder and decoder. */
 /*
- * conv.h
- *
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -22,11 +22,7 @@
 
 /*! \defgroup conv Convolutional encoding and decoding routines
  *  @{
- */
-
-/*! \file conv.h
- * Osmocom convolutional encoder and decoder
- */
+ * \file conv.h */
 
 #pragma once
 
diff --git a/include/osmocom/core/crc16.h b/include/osmocom/core/crc16.h
index f1564bd2..52807af4 100644
--- a/include/osmocom/core/crc16.h
+++ b/include/osmocom/core/crc16.h
@@ -1,4 +1,4 @@
-/*
+/*! \file crc16.h
  * This was copied from the linux kernel and adjusted for our types.
  */
 /*
diff --git a/include/osmocom/core/crcXXgen.h.tpl b/include/osmocom/core/crcXXgen.h.tpl
index 47188090..2c909f92 100644
--- a/include/osmocom/core/crcXXgen.h.tpl
+++ b/include/osmocom/core/crcXXgen.h.tpl
@@ -1,6 +1,6 @@
+/*! \file crcXXgen.h
+ * Osmocom generic CRC routines (for max XX bits poly) header. */
 /*
- * crcXXgen.h
- *
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -24,12 +24,7 @@
 
 /*! \addtogroup crcgen
  *  @{
- */
-
-/*! \file crcXXgen.h
- * Osmocom generic CRC routines (for max XX bits poly) header
- */
-
+ * \file crcXXgen.h.tpl */
 
 #include <stdint.h>
 #include <osmocom/core/bits.h>
diff --git a/include/osmocom/core/crcgen.h b/include/osmocom/core/crcgen.h
index b39b55db..d73e6e80 100644
--- a/include/osmocom/core/crcgen.h
+++ b/include/osmocom/core/crcgen.h
@@ -1,6 +1,6 @@
+/*! \file crcgen.h
+ * Osmocom generic CRC routines global header. */
 /*
- * crcgen.h
- *
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -24,11 +24,7 @@
 
 /*! \defgroup crcgen Osmocom generic CRC routines
  *  @{
- */
-
-/*! \file crcgen.h
- * Osmocom generic CRC routines global header
- */
+ * \file crcgen.h */
 
 #include <osmocom/core/crc8gen.h>
 #include <osmocom/core/crc16gen.h>
diff --git a/include/osmocom/core/defs.h b/include/osmocom/core/defs.h
index 88c41b91..5e5aa90f 100644
--- a/include/osmocom/core/defs.h
+++ b/include/osmocom/core/defs.h
@@ -1,12 +1,12 @@
+/*! \file defs.h
+ *  General definitions that are meant to be included from header files.
+ */
+
 #pragma once
 
 /*! \defgroup utils General-purpose utility functions
  *  @{
- */
-
-/*! \file defs.h
- *  General definitions that are meant to be included from header files.
- */
+ * \file defs.h */
 
 /*! Check for gcc and version.
  *
diff --git a/include/osmocom/core/endian.h b/include/osmocom/core/endian.h
index 621f34e2..6107b12f 100644
--- a/include/osmocom/core/endian.h
+++ b/include/osmocom/core/endian.h
@@ -1,6 +1,5 @@
-#pragma once
-
-/**
+/*! \file endian.h
+ *
  * GNU and FreeBSD have various ways to express the
  * endianess but none of them is similiar enough. This
  * will create two defines that allows to decide on the
@@ -12,6 +11,8 @@
  *
  */
 
+#pragma once
+
 #if defined(__FreeBSD__)
 #include <sys/endian.h>
         #if BYTE_ORDER == LITTLE_ENDIAN
diff --git a/include/osmocom/core/fsm.h b/include/osmocom/core/fsm.h
index fb182f35..2fbb2501 100644
--- a/include/osmocom/core/fsm.h
+++ b/include/osmocom/core/fsm.h
@@ -1,3 +1,7 @@
+/*! \file fsm.h
+ *  Finite State Machine
+ */
+
 #pragma once
 
 #include <stdint.h>
@@ -9,11 +13,7 @@
 
 /*! \defgroup fsm Finite State Machine abstraction
  *  @{
- */
-
-/*! \file fsm.h
- *  Finite State Machine
- */
+ * \file fsm.h */
 
 struct osmo_fsm_inst;
 
diff --git a/include/osmocom/core/gsmtap.h b/include/osmocom/core/gsmtap.h
index 0dc25bb3..1e193158 100644
--- a/include/osmocom/core/gsmtap.h
+++ b/include/osmocom/core/gsmtap.h
@@ -1,8 +1,6 @@
-#pragma once
-
-/* gsmtap header, pseudo-header in front of the actua GSM payload */
-
-/* GSMTAP is a generic header format for GSM protocol captures,
+/*! \file gsmtap.h
+ * gsmtap header, pseudo-header in front of the actua GSM payload.
+ * GSMTAP is a generic header format for GSM protocol captures,
  * it uses the IANA-assigned UDP port number 4729 and carries
  * payload in various formats of GSM interfaces such as Um MAC
  * blocks or Um bursts.
@@ -11,6 +9,8 @@
  * (http://airprobe.org/) or OsmocomBB (http://bb.osmocom.org/)
  */
 
+#pragma once
+
 #include <stdint.h>
 
 /* ====== DO NOT MAKE UNAPPROVED MODIFICATIONS HERE ===== */
diff --git a/include/osmocom/core/gsmtap_util.h b/include/osmocom/core/gsmtap_util.h
index b60257e2..59b81e55 100644
--- a/include/osmocom/core/gsmtap_util.h
+++ b/include/osmocom/core/gsmtap_util.h
@@ -6,8 +6,7 @@
 
 /*! \defgroup gsmtap GSMTAP
  *  @{
- */
-/*! \file gsmtap_util.h */
+ * \file gsmtap_util.h */
 
 uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t rsl_link_id);
 
diff --git a/include/osmocom/core/linuxlist.h b/include/osmocom/core/linuxlist.h
index 5098c5f5..cb753d1d 100644
--- a/include/osmocom/core/linuxlist.h
+++ b/include/osmocom/core/linuxlist.h
@@ -1,11 +1,4 @@
-#pragma once
-
-/*! \defgroup linuxlist Simple doubly linked list implementation
- *  @{
- */
-
-/*!
- * \file linuxlist.h
+/*! \file linuxlist.h
  *
  * Simple doubly linked list implementation.
  *
@@ -16,6 +9,12 @@
  * using the generic single-entry routines.
  */
 
+#pragma once
+
+/*! \defgroup linuxlist Simple doubly linked list implementation
+ *  @{
+ * \file linuxlist.h */
+
 #include <stddef.h>
 
 #ifndef inline
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index bb5aa421..68a9c139 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -2,9 +2,7 @@
 
 /*! \defgroup logging Osmocom logging framework
  *  @{
- */
-
-/*! \file logging.h */
+ * \file logging.h */
 
 #include <stdio.h>
 #include <stdint.h>
diff --git a/include/osmocom/core/loggingrb.h b/include/osmocom/core/loggingrb.h
index dcd7917c..a9fb4047 100644
--- a/include/osmocom/core/loggingrb.h
+++ b/include/osmocom/core/loggingrb.h
@@ -1,5 +1,3 @@
-#pragma once
-
 /* (C) 2012-2013 by Katerina Barone-Adesi <kat.obsc@gmail.com>
  * All Rights Reserved
  *
@@ -19,13 +17,11 @@
  *
  */
 
+#pragma once
 
 /*! \defgroup loggingrb Osmocom ringbuffer-backed logging
  *  @{
- */
-
-/*! \file loggingrb.h
- */
+ * \file loggingrb.h */
 
 struct log_info;
 
diff --git a/include/osmocom/core/macaddr.h b/include/osmocom/core/macaddr.h
index 8de62382..83f0bde3 100644
--- a/include/osmocom/core/macaddr.h
+++ b/include/osmocom/core/macaddr.h
@@ -1,3 +1,5 @@
+/*! \file macaddr.h */
+
 #pragma once
 
 int osmo_macaddr_parse(uint8_t *out, const char *in);
diff --git a/include/osmocom/core/msgb.h b/include/osmocom/core/msgb.h
index 7fad943c..91b7ec7e 100644
--- a/include/osmocom/core/msgb.h
+++ b/include/osmocom/core/msgb.h
@@ -27,9 +27,7 @@
 
 /*! \defgroup msgb Message buffers
  *  @{
- */
-
-/*! \file msgb.h */
+ * \file msgb.h */
 
 #define MSGB_DEBUG
 
diff --git a/include/osmocom/core/msgfile.h b/include/osmocom/core/msgfile.h
index cab97b22..800b4311 100644
--- a/include/osmocom/core/msgfile.h
+++ b/include/osmocom/core/msgfile.h
@@ -1,3 +1,4 @@
+/*! \file msgfile.h */
 /*
  * (C) 2010 by Holger Hans Peter Freyther
  * (C) 2010 by On-Waves
diff --git a/include/osmocom/core/panic.h b/include/osmocom/core/panic.h
index 92c557fe..2bb4240b 100644
--- a/include/osmocom/core/panic.h
+++ b/include/osmocom/core/panic.h
@@ -2,9 +2,7 @@
 
 /*! \addtogroup utils
  *  @{
- */
-
-/*! \file panic.h */
+ * \file panic.h */
 
 #include <stdarg.h>
 
diff --git a/include/osmocom/core/plugin.h b/include/osmocom/core/plugin.h
index aef1dfc9..6db87093 100644
--- a/include/osmocom/core/plugin.h
+++ b/include/osmocom/core/plugin.h
@@ -1,3 +1,5 @@
+/*! \file plugin.h */
+
 #pragma once
 
 int osmo_plugin_load_all(const char *directory);
diff --git a/include/osmocom/core/prim.h b/include/osmocom/core/prim.h
index 7288ba6a..88ae08b5 100644
--- a/include/osmocom/core/prim.h
+++ b/include/osmocom/core/prim.h
@@ -2,9 +2,7 @@
 
 /*! \defgroup prim Osmocom primitives
  *  @{
- */
-
-/*! \file prim.h */
+ * \file prim.h */
 
 #include <stdint.h>
 #include <osmocom/core/msgb.h>
diff --git a/include/osmocom/core/process.h b/include/osmocom/core/process.h
index 1dde0219..8cfca8a7 100644
--- a/include/osmocom/core/process.h
+++ b/include/osmocom/core/process.h
@@ -1,2 +1,3 @@
+/*! \file process.h */
 #warning "Update from osmocom/core/process.h to osmocom/core/application.h"
 #include <osmocom/core/application.h>
diff --git a/include/osmocom/core/rate_ctr.h b/include/osmocom/core/rate_ctr.h
index b75967a0..74414e98 100644
--- a/include/osmocom/core/rate_ctr.h
+++ b/include/osmocom/core/rate_ctr.h
@@ -2,9 +2,7 @@
 
 /*! \defgroup rate_ctr Rate counters
  *  @{
- */
-
-/*! \file rate_ctr.h */
+ * \file rate_ctr.h */
 
 #include <stdint.h>
 
diff --git a/include/osmocom/core/select.h b/include/osmocom/core/select.h
index fe84c5b0..9b5f372b 100644
--- a/include/osmocom/core/select.h
+++ b/include/osmocom/core/select.h
@@ -1,3 +1,7 @@
+/*! \file select.h
+ *  select loop abstraction.
+ */
+
 #pragma once
 
 #include <osmocom/core/linuxlist.h>
@@ -5,11 +9,7 @@
 
 /*! \defgroup select Select loop abstraction
  *  @{
- */
-
-/*! \file select.h
- *  select loop abstraction
- */
+ * \file select.h */
 
 /*! Indicate interest in reading from the file descriptor */
 #define BSC_FD_READ	0x0001
diff --git a/include/osmocom/core/sercomm.h b/include/osmocom/core/sercomm.h
index cf15613a..072f4d9c 100644
--- a/include/osmocom/core/sercomm.h
+++ b/include/osmocom/core/sercomm.h
@@ -1,3 +1,7 @@
+/*! \file sercomm.h
+ *  Osmocom Sercomm HDLC (de)multiplex.
+ */
+
 #ifndef _SERCOMM_H
 #define _SERCOMM_H
 
@@ -5,11 +9,7 @@
 
 /*! \defgroup sercomm Seriall Communications (HDLC)
  *  @{
- */
-
-/*! \file sercomm.h
- *  Osmocom Sercomm HDLC (de)multiplex
- */
+ * \file sercomm.h */
 
 /*! A low sercomm_dlci means high priority.  A high DLCI means low priority */
 enum sercomm_dlci {
diff --git a/include/osmocom/core/serial.h b/include/osmocom/core/serial.h
index e3f7a9ff..39614a47 100644
--- a/include/osmocom/core/serial.h
+++ b/include/osmocom/core/serial.h
@@ -1,6 +1,6 @@
+/*! \file serial.h
+ * Osmocom serial port helpers. */
 /*
- * serial.h
- *
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -22,11 +22,7 @@
 
 /*! \defgroup serial Utility functions to deal with serial ports
  *  @{
- */
-
-/*! \file serial.h
- * Osmocom serial port helpers
- */
+ * \file serial.h */
 
 #pragma once
 
diff --git a/include/osmocom/core/signal.h b/include/osmocom/core/signal.h
index d7132f9d..ae78f152 100644
--- a/include/osmocom/core/signal.h
+++ b/include/osmocom/core/signal.h
@@ -4,8 +4,7 @@
 
 /*! \defgroup signal Intra-application signals
  *  @{
- */
-/*! \file signal.h */
+ * \file signal.h */
 
 /*! subsystem signaling numbers: we split the numberspace for
  * applications and libraries: from 0 to UINT_MAX/2 for applications,
diff --git a/include/osmocom/core/socket.h b/include/osmocom/core/socket.h
index d6a5662b..d2118ef0 100644
--- a/include/osmocom/core/socket.h
+++ b/include/osmocom/core/socket.h
@@ -1,12 +1,11 @@
+/*! \file socket.h
+ *  Osmocom socket convenience functions. */
+
 #pragma once
 
 /*! \defgroup socket Socket convenience functions
  *  @{
- */
-
-/*! \file socket.h
- *  Osmocom socket convenience functions
- */
+ *  \file socket.h */
 
 #include <stdint.h>
 
diff --git a/include/osmocom/core/stat_item.h b/include/osmocom/core/stat_item.h
index 957918ae..4cee8a8b 100644
--- a/include/osmocom/core/stat_item.h
+++ b/include/osmocom/core/stat_item.h
@@ -2,9 +2,7 @@
 
 /*! \defgroup osmo_stat_item Statistics value item
  *  @{
- */
-
-/*! \file stat_item.h */
+ * \file stat_item.h */
 
 #include <stdint.h>
 
diff --git a/include/osmocom/core/stats.h b/include/osmocom/core/stats.h
index 09b836ab..161b34ce 100644
--- a/include/osmocom/core/stats.h
+++ b/include/osmocom/core/stats.h
@@ -1,4 +1,6 @@
-/* (C) 2015 by Sysmocom s.f.m.c. GmbH
+/*! \file stats.h */
+/*
+ * (C) 2015 by Sysmocom s.f.m.c. GmbH
  *
  * All Rights Reserved
  *
diff --git a/include/osmocom/core/strrb.h b/include/osmocom/core/strrb.h
index 2b4d89f0..b87239da 100644
--- a/include/osmocom/core/strrb.h
+++ b/include/osmocom/core/strrb.h
@@ -1,6 +1,7 @@
-#pragma once
-
-/* (C) 2012-2013 by Katerina Barone-Adesi <kat.obsc@gmail.com>
+/*! \file strrb.h
+ * Osmocom string ringbuffer handling routines. */
+/*
+ * (C) 2012-2013 by Katerina Barone-Adesi <kat.obsc@gmail.com>
  * All Rights Reserved
  *
  * This program is free software; you can redistribute it and/or modify
@@ -19,13 +20,11 @@
  *
  */
 
+#pragma once
+
 /*! \defgroup osmo_strrb Osmocom ringbuffers for log strings
  *  @{
- */
-
-/*! \file strrb.h
- *  Osmocom string ringbuffer handling routines
- */
+ * \file strrb.h */
 
 #include <unistd.h>
 #include <stdbool.h>
diff --git a/include/osmocom/core/talloc.h b/include/osmocom/core/talloc.h
index df7ea7fd..191a463f 100644
--- a/include/osmocom/core/talloc.h
+++ b/include/osmocom/core/talloc.h
@@ -1,4 +1,5 @@
-/* Convenience wrapper.  libosmocore used to ship its own internal copy of
+/*! \file talloc.h
+ * Convenience wrapper.  libosmocore used to ship its own internal copy of
  * talloc, before libtalloc became a standard component on most systems */
 #pragma once
 #include <talloc.h>
diff --git a/include/osmocom/core/timer.h b/include/osmocom/core/timer.h
index a039ac82..40b39b90 100644
--- a/include/osmocom/core/timer.h
+++ b/include/osmocom/core/timer.h
@@ -1,3 +1,5 @@
+/*! \file timer.h
+ *  Osmocom timer handling routines. */
 /*
  * (C) 2008, 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
  * All Rights Reserved
@@ -33,11 +35,7 @@
  *      - osmo_timers_update() will call the callbacks and
  *        remove the timers.
  *  @{
- */
-
-/*! \file timer.h
- *  Osmocom timer handling routines.
- */
+ * \file timer.h */
 
 #pragma once
 
diff --git a/include/osmocom/core/timer_compat.h b/include/osmocom/core/timer_compat.h
index 44259afe..77d4ce0a 100644
--- a/include/osmocom/core/timer_compat.h
+++ b/include/osmocom/core/timer_compat.h
@@ -1,3 +1,6 @@
+/*! \file timer_compat.h
+ *  Compatibility header with some helpers
+ */
 /*
  * (C) 2011 Sylvain Munaut <tnt@246tNt.com>
  * All Rights Reserved
@@ -20,11 +23,7 @@
 
 /*! \defgroup timer Osmocom timers
  *  @{
- */
-
-/*! \file timer_compat.h
- *  Compatibility header with some helpers
- */
+ * \file timer_compat.h */
 
 #pragma once
 
diff --git a/include/osmocom/core/utils.h b/include/osmocom/core/utils.h
index ce49cbe7..855e6539 100644
--- a/include/osmocom/core/utils.h
+++ b/include/osmocom/core/utils.h
@@ -5,9 +5,7 @@
 
 /*! \defgroup utils General-purpose utility functions
  *  @{
- */
-
-/*! \file utils.h */
+ * \file utils.h */
 
 /*! Determine number of elements in an array of static size */
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
diff --git a/include/osmocom/core/write_queue.h b/include/osmocom/core/write_queue.h
index 27d090d0..2303f87e 100644
--- a/include/osmocom/core/write_queue.h
+++ b/include/osmocom/core/write_queue.h
@@ -1,4 +1,5 @@
-/* Generic write queue implementation */
+/*! \file write_queue.h
+ * Generic write queue implementation */
 /*
  * (C) 2010 by Holger Hans Peter Freyther
  * (C) 2010 by On-Waves
@@ -24,10 +25,7 @@
 
 /*! \defgroup write_queue Osmocom msgb write queues
  *  @{
- */
-
-/*! \file write_queue.h
- */
+ * \file write_queue.h */
 
 #include <osmocom/core/select.h>
 #include <osmocom/core/msgb.h>
diff --git a/include/osmocom/crypt/auth.h b/include/osmocom/crypt/auth.h
index af4ae153..2f88a3a4 100644
--- a/include/osmocom/crypt/auth.h
+++ b/include/osmocom/crypt/auth.h
@@ -2,9 +2,7 @@
 
 /*! \addtogroup auth
  *  @{
- */
-
-/*! \file auth.h */
+ * \file auth.h */
 
 #include <stdint.h>
 
diff --git a/include/osmocom/crypt/gprs_cipher.h b/include/osmocom/crypt/gprs_cipher.h
index c302f10b..20f0514b 100644
--- a/include/osmocom/crypt/gprs_cipher.h
+++ b/include/osmocom/crypt/gprs_cipher.h
@@ -1,3 +1,5 @@
+/*! \file gprs_cipher.h */
+
 #pragma once
 
 #include <osmocom/core/linuxlist.h>
diff --git a/include/osmocom/ctrl/control_cmd.h b/include/osmocom/ctrl/control_cmd.h
index 3cef9d80..77532e66 100644
--- a/include/osmocom/ctrl/control_cmd.h
+++ b/include/osmocom/ctrl/control_cmd.h
@@ -1,3 +1,5 @@
+/*! \file control_cmd.h */
+
 #pragma once
 
 #include <osmocom/core/msgb.h>
diff --git a/include/osmocom/ctrl/control_if.h b/include/osmocom/ctrl/control_if.h
index 4cd33699..6e49742d 100644
--- a/include/osmocom/ctrl/control_if.h
+++ b/include/osmocom/ctrl/control_if.h
@@ -1,3 +1,5 @@
+/*! \file control_if.h */
+
 #pragma once
 
 #include <osmocom/core/write_queue.h>
diff --git a/include/osmocom/ctrl/control_vty.h b/include/osmocom/ctrl/control_vty.h
index d0ef69f4..af9ee991 100644
--- a/include/osmocom/ctrl/control_vty.h
+++ b/include/osmocom/ctrl/control_vty.h
@@ -1,3 +1,5 @@
+/*! \file control_vty.h */
+
 #pragma once
 
 /* Add the 'ctrl' section to VTY, containing the 'bind' command. */
diff --git a/include/osmocom/ctrl/ports.h b/include/osmocom/ctrl/ports.h
index d28066e6..f974daf4 100644
--- a/include/osmocom/ctrl/ports.h
+++ b/include/osmocom/ctrl/ports.h
@@ -1,6 +1,4 @@
-#pragma once
-
-/*
+/*! \file ports.h
  * TCP port numbers used for CTRL interfaces in osmocom projects. See also the
  * osmocom wiki as well as the osmo-gsm-manuals, which should all be kept in
  * sync with this file:
@@ -8,6 +6,8 @@
  * https://git.osmocom.org/osmo-gsm-manuals/tree/common/chapters/port_numbers.adoc
  */
 
+#pragma once
+
 #define OSMO_CTRL_PORT_BTS	4238
 #define OSMO_CTRL_PORT_NITB_BSC	4249
 #define OSMO_CTRL_PORT_BSC_NAT	4250
diff --git a/include/osmocom/gprs/gprs_bssgp.h b/include/osmocom/gprs/gprs_bssgp.h
index 0e9f7d68..2dead692 100644
--- a/include/osmocom/gprs/gprs_bssgp.h
+++ b/include/osmocom/gprs/gprs_bssgp.h
@@ -1,3 +1,5 @@
+/*! \file gprs_bssgp.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gprs/gprs_bssgp_bss.h b/include/osmocom/gprs/gprs_bssgp_bss.h
index d79b2100..9374e736 100644
--- a/include/osmocom/gprs/gprs_bssgp_bss.h
+++ b/include/osmocom/gprs/gprs_bssgp_bss.h
@@ -1,11 +1,7 @@
-#pragma once
-
-#include <osmocom/core/msgb.h>
-#include <osmocom/gprs/gprs_bssgp.h>
-
-/* GPRS BSSGP protocol implementation as per 3GPP TS 08.18 */
-
-/* (C) 2009-2012 by Harald Welte <laforge@gnumonks.org>
+/*! \file gprs_bssgp_bss.h
+ * GPRS BSSGP protocol implementation as per 3GPP TS 08.18 */
+/*
+ * (C) 2009-2012 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
@@ -24,6 +20,10 @@
  *
  */
 
+#pragma once
+
+#include <osmocom/core/msgb.h>
+#include <osmocom/gprs/gprs_bssgp.h>
 
 uint8_t *bssgp_msgb_tlli_put(struct msgb *msg, uint32_t tlli);
 
diff --git a/include/osmocom/gprs/gprs_msgb.h b/include/osmocom/gprs/gprs_msgb.h
index 9ccc9a55..43471e20 100644
--- a/include/osmocom/gprs/gprs_msgb.h
+++ b/include/osmocom/gprs/gprs_msgb.h
@@ -1,3 +1,5 @@
+/*! \file gprs_msgb.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gprs/gprs_ns.h b/include/osmocom/gprs/gprs_ns.h
index 5ecaed8c..938ad994 100644
--- a/include/osmocom/gprs/gprs_ns.h
+++ b/include/osmocom/gprs/gprs_ns.h
@@ -1,3 +1,5 @@
+/*! \file gprs_ns.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gprs/gprs_ns_frgre.h b/include/osmocom/gprs/gprs_ns_frgre.h
index 72ef7d19..d48ce086 100644
--- a/include/osmocom/gprs/gprs_ns_frgre.h
+++ b/include/osmocom/gprs/gprs_ns_frgre.h
@@ -1,3 +1,5 @@
+/*! \file gprs_ns_frgre.h */
+
 #pragma once
 
 int gprs_ns_frgre_sendmsg(struct gprs_nsvc *nsvc, struct msgb *msg);
diff --git a/include/osmocom/gprs/gprs_rlc.h b/include/osmocom/gprs/gprs_rlc.h
index 5765281b..05d3de60 100644
--- a/include/osmocom/gprs/gprs_rlc.h
+++ b/include/osmocom/gprs/gprs_rlc.h
@@ -1,3 +1,5 @@
+/*! \file gprs_rlc.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gprs/protocol/gsm_04_60.h b/include/osmocom/gprs/protocol/gsm_04_60.h
index 42028bd7..96e9ab78 100644
--- a/include/osmocom/gprs/protocol/gsm_04_60.h
+++ b/include/osmocom/gprs/protocol/gsm_04_60.h
@@ -1,10 +1,11 @@
-#pragma once
-
-/* General Packet Radio Service (GPRS)
+/*! \file gsm_04_60.h
+ * General Packet Radio Service (GPRS).
  * Radio Link Control / Medium Access Control (RLC/MAC) protocol
  * 3GPP TS 04.60 version 8.27.0 Release 1999
  */
 
+#pragma once
+
 #include <stdint.h>
 
 #if OSMO_IS_LITTLE_ENDIAN == 1
diff --git a/include/osmocom/gprs/protocol/gsm_08_16.h b/include/osmocom/gprs/protocol/gsm_08_16.h
index c3dbe695..fc743366 100644
--- a/include/osmocom/gprs/protocol/gsm_08_16.h
+++ b/include/osmocom/gprs/protocol/gsm_08_16.h
@@ -1,16 +1,15 @@
-#pragma once
-
-/* GPRS Networks Service (NS) messages on the Gb interface
+/*! \file gsm_08_16.h
+ * GPRS Networks Service (NS) messages on the Gb interface.
  * 3GPP TS 08.16 version 8.0.1 Release 1999 / ETSI TS 101 299 V8.0.1 (2002-05)
  * 3GPP TS 48.016 version 6.5.0 Release 6 / ETSI TS 148 016 V6.5.0 (2005-11) */
 
+#pragma once
+
 #include <stdint.h>
 
 /*! \addtogroup libgb
  *  @{
- */
-
-/*! \file gprs_ns.h */
+ * \file gprs_ns.h */
 
 /*! Common header of GPRS NS */
 struct gprs_ns_hdr {
diff --git a/include/osmocom/gprs/protocol/gsm_08_18.h b/include/osmocom/gprs/protocol/gsm_08_18.h
index 8bc9a8ea..31794551 100644
--- a/include/osmocom/gprs/protocol/gsm_08_18.h
+++ b/include/osmocom/gprs/protocol/gsm_08_18.h
@@ -1,3 +1,5 @@
+/*! \file gsm_08_18.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/a5.h b/include/osmocom/gsm/a5.h
index 893fb026..fae3fdd4 100644
--- a/include/osmocom/gsm/a5.h
+++ b/include/osmocom/gsm/a5.h
@@ -1,6 +1,6 @@
+/*! \file gsm/a5.h
+ *  Osmocom GSM A5 ciphering algorithm header. */
 /*
- * a5.h
- *
  * Copyright (C) 2011  Sylvain Munaut <tnt@246tNt.com>
  *
  * All Rights Reserved
@@ -29,11 +29,7 @@
 
 /*! \defgroup a5 GSM A5 ciphering algorithm
  *  @{
- */
-
-/*! \file gsm/a5.h
- *  Osmocom GSM A5 ciphering algorithm header
- */
+ * \file a5.h */
 
 /*! Converts a frame number into the 22 bit number used in A5/x
  *  \param[in] fn The true framenumber
diff --git a/include/osmocom/gsm/abis_nm.h b/include/osmocom/gsm/abis_nm.h
index acddb7f4..e031ee10 100644
--- a/include/osmocom/gsm/abis_nm.h
+++ b/include/osmocom/gsm/abis_nm.h
@@ -1,14 +1,12 @@
 #pragma once
 
-/*! \defgroup oml A-bis OML
- *  @{
- */
-
 #include <osmocom/gsm/tlv.h>
 #include <osmocom/gsm/gsm_utils.h>
 #include <osmocom/gsm/protocol/gsm_12_21.h>
 
-/*! \file abis_nm.h */
+/*! \defgroup oml A-bis OML
+ *  @{
+ * \file abis_nm.h */
 
 extern const char abis_nm_ipa_magic[13];
 extern const char abis_nm_osmo_magic[12];
diff --git a/include/osmocom/gsm/apn.h b/include/osmocom/gsm/apn.h
index b4ece3a2..8d353248 100644
--- a/include/osmocom/gsm/apn.h
+++ b/include/osmocom/gsm/apn.h
@@ -1,3 +1,5 @@
+/*! \file apn.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/bitvec_gsm.h b/include/osmocom/gsm/bitvec_gsm.h
index 20741efa..32f0cd2f 100644
--- a/include/osmocom/gsm/bitvec_gsm.h
+++ b/include/osmocom/gsm/bitvec_gsm.h
@@ -5,8 +5,7 @@
 
 /*! \defgroup bitvec helpers for GSM
  *  @{
- */
-/*! \file bitvec_gsm.h */
+ * \file bitvec_gsm.h */
 
 void bitvec_add_range1024(struct bitvec *bv, const struct gsm48_range_1024 *r);
 
diff --git a/include/osmocom/gsm/comp128.h b/include/osmocom/gsm/comp128.h
index 8ff76b10..8626f4bb 100644
--- a/include/osmocom/gsm/comp128.h
+++ b/include/osmocom/gsm/comp128.h
@@ -1,5 +1,5 @@
-/*
- * COMP128 header
+/*! \file comp128.h
+ * COMP128 header.
  *
  * See comp128.c for details
  */
diff --git a/include/osmocom/gsm/comp128v23.h b/include/osmocom/gsm/comp128v23.h
index 31d39335..affe8a21 100644
--- a/include/osmocom/gsm/comp128v23.h
+++ b/include/osmocom/gsm/comp128v23.h
@@ -1,5 +1,5 @@
-/*
- * COMP128v23 header
+/*! \file comp128v23.h
+ * COMP128v23 header.
  *
  * See comp128v23.c for details
  */
diff --git a/include/osmocom/gsm/gan.h b/include/osmocom/gsm/gan.h
index 6f2b5351..efede1d3 100644
--- a/include/osmocom/gsm/gan.h
+++ b/include/osmocom/gsm/gan.h
@@ -1,3 +1,5 @@
+/*! \file gan.h */
+
 #pragma once
 
 #include <osmocom/core/utils.h>
diff --git a/include/osmocom/gsm/gea.h b/include/osmocom/gsm/gea.h
index 3051101d..5c23d2ac 100644
--- a/include/osmocom/gsm/gea.h
+++ b/include/osmocom/gsm/gea.h
@@ -1,5 +1,5 @@
-/*
- * GEA3 header
+/*! \file gea.h
+ * GEA3 header.
  *
  * See gea.c for details
  */
diff --git a/include/osmocom/gsm/gsm0341.h b/include/osmocom/gsm/gsm0341.h
index 29ba3e16..2fc83e4b 100644
--- a/include/osmocom/gsm/gsm0341.h
+++ b/include/osmocom/gsm/gsm0341.h
@@ -1,3 +1,5 @@
+/*! \file gsm0341.h */
+
 #pragma once
 
 #include <osmocom/gsm/protocol/gsm_03_41.h>
diff --git a/include/osmocom/gsm/gsm0411_smc.h b/include/osmocom/gsm/gsm0411_smc.h
index 89964fa1..0cd1f94a 100644
--- a/include/osmocom/gsm/gsm0411_smc.h
+++ b/include/osmocom/gsm/gsm0411_smc.h
@@ -1,3 +1,5 @@
+/*! \file gsm0411_smc.h */
+
 #pragma once
 
 #include <osmocom/core/timer.h>
diff --git a/include/osmocom/gsm/gsm0411_smr.h b/include/osmocom/gsm/gsm0411_smr.h
index bc908a75..19f9c5da 100644
--- a/include/osmocom/gsm/gsm0411_smr.h
+++ b/include/osmocom/gsm/gsm0411_smr.h
@@ -1,3 +1,5 @@
+/*! \file gsm0411_smr.h */
+
 #pragma once
 
 #include <osmocom/gsm/protocol/gsm_04_11.h>
diff --git a/include/osmocom/gsm/gsm0411_utils.h b/include/osmocom/gsm/gsm0411_utils.h
index 70050105..1c51111e 100644
--- a/include/osmocom/gsm/gsm0411_utils.h
+++ b/include/osmocom/gsm/gsm0411_utils.h
@@ -1,3 +1,5 @@
+/*! \file gsm0411_utils.h */
+
 #pragma once
 
 #include <time.h>
diff --git a/include/osmocom/gsm/gsm0480.h b/include/osmocom/gsm/gsm0480.h
index 6ca23e98..672ffe5e 100644
--- a/include/osmocom/gsm/gsm0480.h
+++ b/include/osmocom/gsm/gsm0480.h
@@ -1,3 +1,5 @@
+/*! \file gsm0480.h */
+
 #pragma once
 
 #include <osmocom/core/defs.h>
diff --git a/include/osmocom/gsm/gsm0502.h b/include/osmocom/gsm/gsm0502.h
index 6ee5a600..fe5cf7e1 100644
--- a/include/osmocom/gsm/gsm0502.h
+++ b/include/osmocom/gsm/gsm0502.h
@@ -1,3 +1,5 @@
+/*! \file gsm0502.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/gsm0808.h b/include/osmocom/gsm/gsm0808.h
index 9be229c6..4369cabe 100644
--- a/include/osmocom/gsm/gsm0808.h
+++ b/include/osmocom/gsm/gsm0808.h
@@ -1,4 +1,6 @@
-/* (C) 2009,2010 by Holger Hans Peter Freyther <zecke@selfish.org>
+/*! \file gsm0808.h */
+/*
+ * (C) 2009,2010 by Holger Hans Peter Freyther <zecke@selfish.org>
  * (C) 2009,2010 by On-Waves
  * All Rights Reserved
  *
diff --git a/include/osmocom/gsm/gsm0808_utils.h b/include/osmocom/gsm/gsm0808_utils.h
index 0937630d..57ba1713 100644
--- a/include/osmocom/gsm/gsm0808_utils.h
+++ b/include/osmocom/gsm/gsm0808_utils.h
@@ -1,4 +1,6 @@
-/* (C) 2016 by Sysmocom s.f.m.c. GmbH
+/*! \file gsm0808_utils.h */
+/*
+ * (C) 2016 by Sysmocom s.f.m.c. GmbH
  * All Rights Reserved
  *
  * Author: Philipp Maier
diff --git a/include/osmocom/gsm/gsm23003.h b/include/osmocom/gsm/gsm23003.h
index 29e646cc..2bc75837 100644
--- a/include/osmocom/gsm/gsm23003.h
+++ b/include/osmocom/gsm/gsm23003.h
@@ -1,4 +1,7 @@
+/*! \file gsm23003.h */
+
 #pragma once
+
 #include <stdint.h>
 
 /* 23.003 Chapter 12.1 */
diff --git a/include/osmocom/gsm/gsm48.h b/include/osmocom/gsm/gsm48.h
index 6a52c2d8..424748ee 100644
--- a/include/osmocom/gsm/gsm48.h
+++ b/include/osmocom/gsm/gsm48.h
@@ -1,3 +1,5 @@
+/*! \file gsm48.h */
+
 #pragma once
 
 #include <osmocom/gsm/tlv.h>
diff --git a/include/osmocom/gsm/gsm48_ie.h b/include/osmocom/gsm/gsm48_ie.h
index 84454865..f7cc24ea 100644
--- a/include/osmocom/gsm/gsm48_ie.h
+++ b/include/osmocom/gsm/gsm48_ie.h
@@ -1,3 +1,5 @@
+/*! \file gsm48_ie.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/gsm_utils.h b/include/osmocom/gsm/gsm_utils.h
index e76d9ee8..998f681e 100644
--- a/include/osmocom/gsm/gsm_utils.h
+++ b/include/osmocom/gsm/gsm_utils.h
@@ -1,4 +1,5 @@
-/* GSM utility functions, e.g. coding and decoding */
+/*! \file gsm_utils.h
+ * GSM utility functions, e.g. coding and decoding. */
 /*
  * (C) 2008 by Daniel Willmann <daniel@totalueberwachung.de>
  * (C) 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
diff --git a/include/osmocom/gsm/gsup.h b/include/osmocom/gsm/gsup.h
index 04b31d0b..886ea5da 100644
--- a/include/osmocom/gsm/gsup.h
+++ b/include/osmocom/gsm/gsup.h
@@ -1,6 +1,7 @@
-/* Osmocom Generic Subscriber Update Protocol message encoder/decoder */
-
-/* (C) 2014 by sysmocom s.f.m.c. GmbH, Author: Jacob Erlbeck
+/*! \file gsup.h
+ * Osmocom Generic Subscriber Update Protocol message encoder/decoder. */
+/*
+ * (C) 2014 by sysmocom s.f.m.c. GmbH, Author: Jacob Erlbeck
  * (C) 2016 by Harald Welte <laforge@gnumonks.org>
  * All Rights Reserved
  *
diff --git a/include/osmocom/gsm/ipa.h b/include/osmocom/gsm/ipa.h
index cabee139..7e1d7237 100644
--- a/include/osmocom/gsm/ipa.h
+++ b/include/osmocom/gsm/ipa.h
@@ -1,3 +1,5 @@
+/*! \file ipa.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/kasumi.h b/include/osmocom/gsm/kasumi.h
index 222aece8..d9de10b4 100644
--- a/include/osmocom/gsm/kasumi.h
+++ b/include/osmocom/gsm/kasumi.h
@@ -1,5 +1,5 @@
-/*
- * KASUMI header
+/*! \file kasumi.h
+ * KASUMI header.
  *
  * See kasumi.c for details
  * The parameters are described in TS 135 202.
diff --git a/include/osmocom/gsm/l1sap.h b/include/osmocom/gsm/l1sap.h
index 322c7ec1..01f61ced 100644
--- a/include/osmocom/gsm/l1sap.h
+++ b/include/osmocom/gsm/l1sap.h
@@ -1,3 +1,5 @@
+/*! \file l1sap.h */
+
 #pragma once
 
 #include <osmocom/core/prim.h>
diff --git a/include/osmocom/gsm/lapd_core.h b/include/osmocom/gsm/lapd_core.h
index 8d3a0f81..cfc357a7 100644
--- a/include/osmocom/gsm/lapd_core.h
+++ b/include/osmocom/gsm/lapd_core.h
@@ -1,3 +1,6 @@
+/*! \file lapd_core.h
+ * primitive related stuff
+ */
 #pragma once
 
 #include <stdint.h>
@@ -8,10 +11,7 @@
 
 /*! \defgroup lapd LAPD implementation common part
  *  @{
- */
-
-/*! \file lapd_core.h
- * primitive related stuff
+ * \file lapd_core.h
  */
 
 /*! LAPD related primitives (L2<->L3 SAP)*/
diff --git a/include/osmocom/gsm/lapdm.h b/include/osmocom/gsm/lapdm.h
index ec14cddc..e01d065a 100644
--- a/include/osmocom/gsm/lapdm.h
+++ b/include/osmocom/gsm/lapdm.h
@@ -5,9 +5,7 @@
 
 /*! \defgroup lapdm LAPDm implementation according to GSM TS 04.06
  *  @{
- */
-
-/*! \file lapdm.h */
+ * \file lapdm.h */
 
 /*! LAPDm mode/role */
 enum lapdm_mode {
diff --git a/include/osmocom/gsm/meas_rep.h b/include/osmocom/gsm/meas_rep.h
index 90c981dd..79f9f06b 100644
--- a/include/osmocom/gsm/meas_rep.h
+++ b/include/osmocom/gsm/meas_rep.h
@@ -1,3 +1,5 @@
+/*! \file meas_rep.h */
+
 #pragma once
 
 #include <stdint.h>
diff --git a/include/osmocom/gsm/mncc.h b/include/osmocom/gsm/mncc.h
index 171db7ab..f2450d9c 100644
--- a/include/osmocom/gsm/mncc.h
+++ b/include/osmocom/gsm/mncc.h
@@ -1,3 +1,5 @@
+/*! \file mncc.h */
+
 #pragma once
 
 #include <osmocom/gsm/protocol/gsm_04_08.h>
diff --git a/include/osmocom/gsm/oap.h b/include/osmocom/gsm/oap.h
index fba22c78..ef83b794 100644
--- a/include/osmocom/gsm/oap.h
+++ b/include/osmocom/gsm/oap.h
@@ -1,6 +1,7 @@
-/* Osmocom Authentication Protocol message encoder/decoder */
-
-/* (C) 2015-2016 by sysmocom s.f.m.c. GmbH
+/*! \file oap.h
+ * 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/include/osmocom/gsm/prim.h b/include/osmocom/gsm/prim.h
index 5f61dc7c..386b7d89 100644
--- a/include/osmocom/gsm/prim.h
+++ b/include/osmocom/gsm/prim.h
@@ -1,3 +1,5 @@
+/*! \file prim.h */
+
 #pragma once
 
 #include <osmocom/core/prim.h>
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 */
 
diff --git a/include/osmocom/gsm/rsl.h b/include/osmocom/gsm/rsl.h
index 93e27a14..3d9c66f5 100644
--- a/include/osmocom/gsm/rsl.h
+++ b/include/osmocom/gsm/rsl.h
@@ -7,9 +7,7 @@
 
 /*! \defgroup rsl RSL
  *  @{
- */
-
-/*! \file rsl.h */
+ * \file rsl.h */
 
 void rsl_init_rll_hdr(struct abis_rsl_rll_hdr *dh, uint8_t msg_type);
 
diff --git a/include/osmocom/gsm/rxlev_stat.h b/include/osmocom/gsm/rxlev_stat.h
index 7183b173..7aa35cd5 100644
--- a/include/osmocom/gsm/rxlev_stat.h
+++ b/include/osmocom/gsm/rxlev_stat.h
@@ -1,3 +1,5 @@
+/*! \file rxlev_stat.h */
+
 #pragma once
 
 #define NUM_RXLEVS 32
diff --git a/include/osmocom/gsm/sysinfo.h b/include/osmocom/gsm/sysinfo.h
index f3e0f22f..8e26f996 100644
--- a/include/osmocom/gsm/sysinfo.h
+++ b/include/osmocom/gsm/sysinfo.h
@@ -1,3 +1,5 @@
+/*! \file sysinfo.h */
+
 #pragma once
 
 #include <stdbool.h>
diff --git a/include/osmocom/gsm/tlv.h b/include/osmocom/gsm/tlv.h
index fa3b6564..c3568400 100644
--- a/include/osmocom/gsm/tlv.h
+++ b/include/osmocom/gsm/tlv.h
@@ -9,8 +9,7 @@
 
 /*! \defgroup tlv GSM L3 compatible TLV parser
  *  @{
- */
-/*! \file tlv.h */
+ * \file tlv.h */
 
 /* Terminology / wording
 		tag	length		value	(in bits)
diff --git a/include/osmocom/sim/class_tables.h b/include/osmocom/sim/class_tables.h
index ad89d949..d5be39dd 100644
--- a/include/osmocom/sim/class_tables.h
+++ b/include/osmocom/sim/class_tables.h
@@ -1,7 +1,6 @@
-#pragma once
-
-/* simtrace - tables determining APDU case for card emulation
- *
+/*! \file class_tables.h
+ * simtrace - tables determining APDU case for card emulation. */
+/*
  * (C) 2016 by Harald Welte <laforge@gnumonks.org>
  *
  *  This program is free software; you can redistribute it and/or modify
@@ -18,6 +17,8 @@
  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+#pragma once
+
 #include <stdint.h>
 
 struct osim_cla_ins_case {
diff --git a/include/osmocom/sim/sim.h b/include/osmocom/sim/sim.h
index eb954807..680cad15 100644
--- a/include/osmocom/sim/sim.h
+++ b/include/osmocom/sim/sim.h
@@ -1,3 +1,7 @@
+/*! \file sim.h
+ * Routines for helping with SIM (ISO/IEC 7816-4 more generally) communication.
+ */
+
 #ifndef _OSMOCOM_SIM_H
 #define _OSMOCOM_SIM_H
 
@@ -6,11 +10,6 @@
 
 #define APDU_HDR_LEN	5
 
-/*!
- * \file sim.h
- * Routines for helping with SIM (ISO/IEC 7816-4 more generally) communication.
- */
-
 /*! command-response pairs cases
  *
  * Enumeration used to identify the APDU structure based on command-response pair case , as specified in ISO/IEC 7816-3:2006(E) §12.1.
diff --git a/include/osmocom/vty/buffer.h b/include/osmocom/vty/buffer.h
index 56c28f04..b5cce8a3 100644
--- a/include/osmocom/vty/buffer.h
+++ b/include/osmocom/vty/buffer.h
@@ -1,5 +1,6 @@
+/*! \file buffer.h
+ * Buffering to output and input. */
 /*
- * Buffering to output and input.
  * Copyright (C) 1998 Kunihiro Ishiguro
  *
  * This file is part of GNU Zebra.
diff --git a/include/osmocom/vty/command.h b/include/osmocom/vty/command.h
index 9a072d73..0fa5175a 100644
--- a/include/osmocom/vty/command.h
+++ b/include/osmocom/vty/command.h
@@ -1,5 +1,6 @@
+/*! \file command.h
+ * Zebra configuration command interface routine. */
 /*
- * Zebra configuration command interface routine
  * Copyright (C) 1997, 98 Kunihiro Ishiguro
  *
  * This file is part of GNU Zebra.
@@ -28,8 +29,7 @@
 
 /*! \defgroup command VTY Command
  *  @{
- */
-/*! \file command.h */
+ * \file command.h */
 
 /*! Host configuration variable */
 struct host {
diff --git a/include/osmocom/vty/logging.h b/include/osmocom/vty/logging.h
index 544d1177..9bafb98f 100644
--- a/include/osmocom/vty/logging.h
+++ b/include/osmocom/vty/logging.h
@@ -1,3 +1,5 @@
+/*! \file logging.h */
+
 #pragma once
 
 #define LOGGING_STR	"Configure log message to this terminal\n"
diff --git a/include/osmocom/vty/misc.h b/include/osmocom/vty/misc.h
index b3fb644d..545955c4 100644
--- a/include/osmocom/vty/misc.h
+++ b/include/osmocom/vty/misc.h
@@ -1,3 +1,5 @@
+/*! \file misc.h */
+
 #pragma once
 
 #include <osmocom/vty/vty.h>
diff --git a/include/osmocom/vty/ports.h b/include/osmocom/vty/ports.h
index a6043b3c..8f8ef758 100644
--- a/include/osmocom/vty/ports.h
+++ b/include/osmocom/vty/ports.h
@@ -1,6 +1,4 @@
-#pragma once
-
-/*
+/*! \file ports.h
  * TCP port numbers used for VTY interfaces in osmocom projects. See also the
  * osmocom wiki as well as the osmo-gsm-manuals, which should all be kept in
  * sync with this file:
@@ -8,6 +6,8 @@
  * https://git.osmocom.org/osmo-gsm-manuals/tree/common/chapters/port_numbers.adoc
  */
 
+#pragma once
+
 /* 4238 used by osmo-bts control interface */
 #define OSMO_VTY_PORT_STP	4239
 #define OSMO_VTY_PORT_PCU	4240	/* also: osmo_pcap_client */
diff --git a/include/osmocom/vty/stats.h b/include/osmocom/vty/stats.h
index 3851b4df..76299284 100644
--- a/include/osmocom/vty/stats.h
+++ b/include/osmocom/vty/stats.h
@@ -1,3 +1,5 @@
+/*! \file stats.h */
+
 #pragma once
 
 void osmo_stats_vty_add_cmds();
diff --git a/include/osmocom/vty/telnet_interface.h b/include/osmocom/vty/telnet_interface.h
index bca91564..d653466a 100644
--- a/include/osmocom/vty/telnet_interface.h
+++ b/include/osmocom/vty/telnet_interface.h
@@ -1,5 +1,7 @@
-/* minimalistic telnet/network interface it might turn into a wire interface */
-/* (C) 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
+/*! \file telnet_interface.h
+ * minimalistic telnet/network interface it might turn into a wire interface */
+/*
+ * (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
@@ -27,9 +29,7 @@
 
 /*! \defgroup telnet_interface Telnet Interface
  *  @{
- */
-
-/*! \file telnet_interface.h */
+ * \file telnet_interface.h */
 
 /*! A telnet connection */
 struct telnet_connection {
diff --git a/include/osmocom/vty/vector.h b/include/osmocom/vty/vector.h
index c00804de..0a639ad9 100644
--- a/include/osmocom/vty/vector.h
+++ b/include/osmocom/vty/vector.h
@@ -1,5 +1,6 @@
+/*! \file vector.h
+ * Generic vector interface header. */
 /*
- * Generic vector interface header.
  * Copyright (C) 1997, 98 Kunihiro Ishiguro
  *
  * This file is part of GNU Zebra.
diff --git a/include/osmocom/vty/vty.h b/include/osmocom/vty/vty.h
index d59f5d47..544e1fa0 100644
--- a/include/osmocom/vty/vty.h
+++ b/include/osmocom/vty/vty.h
@@ -5,8 +5,7 @@
 
 /*! \defgroup vty VTY (Virtual TTY) interface
  *  @{
- */
-/*! \file vty.h */
+ * \file vty.h */
 
 /* GCC have printf type attribute check.  */
 #ifdef __GNUC__