progdocs: Avoid 'name' with Doxygen \file.

Fixes four misuses of the parameter 'name'. Additionally, for
consistency and to avoid such an issue in future, those few other
places, which used '\file name', were changed just to '\file'. Then,
Doxygen uses the name of the current file.

ASTERISK-29733

Change-Id: I0c18b4c863c6988b138c77448057349a9ee7052d

include/asterisk/calendar.h

@@ -27,7 +27,9 @@
 #include "asterisk/dial.h"
 #include "asterisk/module.h"
 
-/*! \file calendar.h
+/*!
+ * \file
+ *
  * \brief A general API for managing calendar events with Asterisk
  *
  * \author Terry Wilson <twilson@digium.com>

include/asterisk/dlinkedlists.h

@@ -28,7 +28,8 @@
 #include "asterisk/lock.h"
 
 /*!
- * \file dlinkedlists.h
+ * \file
+ *
  * \brief A set of macros to manage doubly-linked lists.
  */
 

include/asterisk/enum.h

@@ -16,9 +16,11 @@
  * at the top of the source tree.
  */
 
-/*!	\file enum.h
+/*!
-	\brief DNS and ENUM functions
+ * \file
-*/
+ *
+ * \brief DNS and ENUM functions
+ */
 
 #ifndef _ASTERISK_ENUM_H
 #define _ASTERISK_ENUM_H

include/asterisk/http.h

@@ -24,8 +24,10 @@
 #include "asterisk/linkedlists.h"
 
 /*!
- * \file http.h
+ * \file
+ *
  * \brief Support for Private Asterisk HTTP Servers.
+ *
  * \note Note: The Asterisk HTTP servers are extremely simple and minimal and
  *      only support the "GET" method.
  *

include/asterisk/http_websocket.h

@@ -31,7 +31,8 @@
 #define AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT_STR "100"
 
 /*!
- * \file http_websocket.h
+ * \file
+ *
  * \brief Support for WebSocket connections within the Asterisk HTTP server and client
  *        WebSocket connections to a server.
  *

include/asterisk/iostream.h

@@ -20,7 +20,7 @@
 #define _ASTERISK_IOSTREAM_H
 
 /*!
- * \file iostream.h
+ * \file
  *
  * \brief Generic abstraction for input/output streams.
  */

include/asterisk/linkedlists.h

@@ -23,7 +23,8 @@
 #include "asterisk/lock.h"
 
 /*!
- * \file linkedlists.h
+ * \file
+ *
  * \brief A set of macros to manage forward-linked lists.
  */
 

include/asterisk/logger.h

@@ -17,10 +17,11 @@
  */
 
 /*!
-  \file logger.h
+ * \file
-  \brief Support for logging to various files, console and syslog
+ *
-	Configuration in file logger.conf
+ * \brief Support for logging to various files, console and syslog
-*/
+ *        Configuration in file logger.conf
+ */
 
 #ifndef _ASTERISK_LOGGER_H
 #define _ASTERISK_LOGGER_H

include/asterisk/res_prometheus.h

@@ -20,7 +20,7 @@
 #define RES_PROMETHEUS_H__
 
 /*!
- * \file res_prometheus
+ * \file
  *
  * \brief Asterisk Prometheus Metrics
  *

include/asterisk/sdp_srtp.h

@@ -16,7 +16,8 @@
  * at the top of the source tree.
  */
 
-/*! \file sdp_srtp.h
+/*!
+ * \file
  *
  * \brief SRTP and SDP Security descriptions
  *

include/asterisk/srv.h

@@ -23,7 +23,8 @@
 #ifndef _ASTERISK_SRV_H
 #define _ASTERISK_SRV_H
 
-/*! \file srv.h
+/*!
+ * \file
  *
  * \brief Support for DNS SRV records, used in to locate SIP services.
  *

include/asterisk/stun.h

@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file stun.h
+ * \file
+ *
  * \brief STUN support.
  *
  * STUN is defined in RFC 3489.

include/asterisk/syslog.h

@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file syslog.h
+ * \file
+ *
  * \brief Syslog support functions for Asterisk logging.
  */
 

include/asterisk/taskprocessor.h

@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file taskprocessor.h
+ * \file
+ *
  * \brief An API for managing task processing threads that can be shared across modules
  *
  * \author Dwayne M. Hubbard <dhubbard@digium.com>

include/asterisk/tcptls.h

@@ -17,9 +17,10 @@
  */
 
 /*!
- * \file tcptls.h
+ * \file
  *
  * \brief Generic support for tcp/tls servers in Asterisk.
+ *
  * \note In order to have TLS/SSL support, we need the openssl libraries.
  * Still we can decide whether or not to use them by commenting
  * in or out the DO_SSL macro.

include/asterisk/threadstorage.h

@@ -17,10 +17,12 @@
  */
 
 /*!
- * \file threadstorage.h
+ * \file
- * \author Russell Bryant <russell@digium.com>
+ *
  * \brief Definitions to aid in the use of thread local storage
  *
+ * \author Russell Bryant <russell@digium.com>
+ *
  * \arg \ref AstThreadStorage
  */
 

include/asterisk/timing.h

@@ -18,7 +18,7 @@
  */
 
 /*!
-	\file timing.h
+	\file
 	\brief Timing source management
 	\author Kevin P. Fleming <kpfleming@digium.com>
 	\author Russell Bryant <russell@digium.com>

main/optional_api.c

@@ -24,8 +24,8 @@
 
 #if defined(OPTIONAL_API)
 
-/*
+/*!
- * \file Optional API innards.
+ * \file
  *
  * The calls to ast_optional_api_*() happen implicitly from \c __constructor__
  * calls which are defined in header files. This means that some number of them

res/prometheus/prometheus_internal.h

@@ -20,11 +20,11 @@
 #define PROMETHEUS_INTERNAL_H__
 
 /*!
- * \file prometheus_internal
+ * \file
  *
  * \brief Prometheus Metric Internal API
  *
- * This module provides internal APIs for \file res_prometheus.
+ * This module provides internal APIs for res_prometheus.
  * It should not be used outsize of that module, and should
  * typically only provide intialization functions for units that
  * want to register metrics / handlers with the core API.

res/res_srtp.c

@@ -18,7 +18,8 @@
  * Builds on libSRTP http://srtp.sourceforge.net
  */
 
-/*! \file res_srtp.c
+/*!
+ * \file
  *
  * \brief Secure RTP (SRTP)
  *