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

38 files changed, 115 insertions, 163 deletions

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>