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

9 files changed, 28 insertions, 20 deletions

diff --git a/src/vty/buffer.c b/src/vty/buffer.c
index 8862da92..1935aa11 100644
--- a/src/vty/buffer.c
+++ b/src/vty/buffer.c
@@ -1,5 +1,6 @@
+/*! \file buffer.c
+ * Buffering of output and input. */
 /*
- * Buffering of output and input.
  * Copyright (C) 1998 Kunihiro Ishiguro
  *
  * This file is part of GNU Zebra.
diff --git a/src/vty/command.c b/src/vty/command.c
index a0824d39..33862c0d 100644
--- a/src/vty/command.c
+++ b/src/vty/command.c
@@ -44,8 +44,8 @@ Boston, MA  02110-1301, USA. */
 /*! \addtogroup command
  *  @{
  *  VTY command handling
- */
-/*! \file command.c */
+ *
+ * \file command.c */
 
 #define CONFIGFILE_MASK 022
 
diff --git a/src/vty/fsm_vty.c b/src/vty/fsm_vty.c
index acc8ca60..345be667 100644
--- a/src/vty/fsm_vty.c
+++ b/src/vty/fsm_vty.c
@@ -1,5 +1,7 @@
-/* Osmocom FSM introspection via VTY */
-/* (C) 2016 by Harald Welte <laforge@gnumonks.org>
+/*! \file fsm_vty.c
+ * Osmocom FSM introspection via VTY. */
+/*
+ * (C) 2016 by Harald Welte <laforge@gnumonks.org>
  * All Rights Reserved
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/src/vty/logging_vty.c b/src/vty/logging_vty.c
index 4cb13792..758f0b96 100644
--- a/src/vty/logging_vty.c
+++ b/src/vty/logging_vty.c
@@ -1,5 +1,7 @@
-/* OpenBSC logging helper for the VTY */
-/* (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
+/*! \file logging_vty.c
+ * OpenBSC logging helper for the VTY. */
+/*
+ * (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
  * (C) 2009-2014 by Holger Hans Peter Freyther
  * All Rights Reserved
  *
diff --git a/src/vty/stats_vty.c b/src/vty/stats_vty.c
index 05578208..57cdd308 100644
--- a/src/vty/stats_vty.c
+++ b/src/vty/stats_vty.c
@@ -1,5 +1,7 @@
-/* OpenBSC stats helper for the VTY */
-/* (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
+/*! \file stats_vty.c
+ * OpenBSC stats helper for the VTY. */
+/*
+ * (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
  * (C) 2009-2014 by Holger Hans Peter Freyther
  * (C) 2015      by Sysmocom s.f.m.c. GmbH
  * All Rights Reserved
diff --git a/src/vty/telnet_interface.c b/src/vty/telnet_interface.c
index d59516c1..f82a7ff1 100644
--- a/src/vty/telnet_interface.c
+++ b/src/vty/telnet_interface.c
@@ -1,4 +1,5 @@
-/* minimalistic telnet/network interface it might turn into a wire interface */
+/*! \file telnet_interface.c
+ * minimalistic telnet/network interface it might turn into a wire interface */
 /* (C) 2009 by Holger Hans Peter Freyther <zecke@selfish.org>
  * All Rights Reserved
  *
@@ -44,8 +45,8 @@
  *  access.  This telnet server gets linked into each libosmovty-using
  *  process in order to enable interactive command-line introspection,
  *  interaction and configuration.
- */
-/*! \file telnet_interface.c */
+ *
+ * \file telnet_interface.c */
 
 /* per connection data */
 LLIST_HEAD(active_connections);
diff --git a/src/vty/utils.c b/src/vty/utils.c
index 267d76e8..9d1bdf9e 100644
--- a/src/vty/utils.c
+++ b/src/vty/utils.c
@@ -1,6 +1,7 @@
-/* utility routines for printing common objects in the Osmocom world */
-
-/* (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
+/*! \file utils.c
+ * Utility routines for printing common objects in the Osmocom world. */
+/*
+ * (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
  *
@@ -36,8 +37,6 @@
 
 #include <osmocom/vty/vty.h>
 
-/* \file utils.c */
-
 /*! \addtogroup rate_ctr
  *  @{
  */
diff --git a/src/vty/vector.c b/src/vty/vector.c
index c21bca70..ee07cbd2 100644
--- a/src/vty/vector.c
+++ b/src/vty/vector.c
@@ -1,4 +1,6 @@
-/* Generic vector interface routine
+/*! \file vector.c
+ * Generic vector interface routine. */
+/*
  * Copyright (C) 1997 Kunihiro Ishiguro
  *
  * This file is part of GNU Zebra.
diff --git a/src/vty/vty.c b/src/vty/vty.c
index 6e60eb75..644d4ed6 100644
--- a/src/vty/vty.c
+++ b/src/vty/vty.c
@@ -68,8 +68,7 @@
 
 /* \addtogroup vty
  * @{
- */
-/*! \file vty.c */
+ * \file vty.c */
 
 #define SYSCONFDIR "/usr/local/etc"