doxygen: Fix doxygen errors

This patch fixes a number of errors and warning messages in the doxygen
log. Specifically, it addresses:
* A number of files incorrectly places a '\brief' tag immediately after
  a '\file' tag. Doing so emits a warning, as '\file' takes an optional
  argument specifying which file the doxygen comment is for. As '\brief'
  is not a file, doxygen was unamused.
* A grouping of Stasis Topics and Messages in rtp_engine.h was
  incorrectly terminated. We now correctly terminate the grouping, which
  prevents members of rtp_engine.h from showing up in the wrong group.
* Group indicators which are not part of the Stasis Topics and Messages
  group were removed. Group indicators without an \addtogroup or
  \ingroup have no meaning.

Change-Id: Ia1415ffec6767e27233ae1cae5ed5970de5656d4

diff --git a/include/asterisk/event.h b/include/asterisk/event.h
index 7eea0581d962dfa56101d4ecf4b7a9b500d223f5..dbc080da8f8e23b9339083a23fa801336a47df5b 100644 (file)
--- a/include/asterisk/event.h
+++ b/include/asterisk/event.h
@@ -35,7 +35,7 @@
  * modules in Asterisk.
  *  - CEL uses the \ref ast_event representation to pass information to registered
  *    backends.
- *  - The \file res_corosync module publishes \ref ast_event representations of
+ *  - The \file res_corosync.c module publishes \ref ast_event representations of
  *    information to other Asterisk instances in a cluster.
  *  - Security event represent their event types and data using this system.
  *  - Theoretically, any \ref stasis message can use this system to pass

diff --git a/include/asterisk/rtp_engine.h b/include/asterisk/rtp_engine.h
index a94cb421368c3ad3b01d7295e30ad97d477e60cb..c7f6511f90eb135cef2b0a805e5c418b1a27e3bd 100644 (file)
--- a/include/asterisk/rtp_engine.h
+++ b/include/asterisk/rtp_engine.h
@@ -2316,7 +2316,7 @@ struct stasis_message_type *ast_rtp_rtcp_received_type(void);
  */
 struct stasis_topic *ast_rtp_topic(void);
 
-/* }@ */
+/* @} */
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }

diff --git a/include/asterisk/sem.h b/include/asterisk/sem.h
index 6d655d63e45a3e4aeea5781b3e19a9fc14274df4..fcab82a5e2872886466bda8253988f98b70205c9 100644 (file)
--- a/include/asterisk/sem.h
+++ b/include/asterisk/sem.h
@@ -20,7 +20,9 @@
 #define ASTERISK_SEMAPHORE_H
 
 /*!
- * \file Asterisk semaphore API
+ * \file
+ *
+ * \brief Asterisk semaphore API
  *
  * This API is a thin wrapper around the POSIX semaphore API (when available),
  * so see the POSIX documentation for further details.

diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h
index 0b1b1e83f88ca01f5969af5c7993a794d0816af2..aa681e13ea8b9c1b11f2b80043b7893a7e0b343f 100644 (file)
--- a/include/asterisk/stasis.h
+++ b/include/asterisk/stasis.h
@@ -173,8 +173,6 @@
 #include "asterisk/utils.h"
 #include "asterisk/event.h"
 
-/*! @{ */
-
 /*!
  * \brief Metadata about a \ref stasis_message.
  * \since 12
@@ -451,10 +449,6 @@ struct ast_manager_event_blob *stasis_message_to_ami(
 struct ast_event *stasis_message_to_event(
        struct stasis_message *message);
 
-/*! @} */
-
-/*! @{ */
-
 /*!
  * \brief A topic to which messages may be posted, and subscribers, well, subscribe
  * \since 12
@@ -508,10 +502,6 @@ void stasis_publish(struct stasis_topic *topic, struct stasis_message *message);
  */
 void stasis_publish_sync(struct stasis_subscription *sub, struct stasis_message *message);
 
-/*! @} */
-
-/*! @{ */
-
 /*!
  * \brief Callback function type for Stasis subscriptions.
  * \param data Data field provided with subscription.
@@ -699,8 +689,6 @@ struct stasis_message_type *stasis_subscription_change_type(void);
 
 /*! @} */
 
-/*! @{ */
-
 /*!
  * \brief Pool for topic aggregation
  */
@@ -723,8 +711,6 @@ struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_t
  */
 struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name);
 
-/*! @} */
-
 /*! \addtogroup StasisTopicsAndMessages
  * @{
  */
@@ -757,8 +743,6 @@ struct stasis_message_type *stasis_cache_clear_type(void);
 
 /*! @} */
 
-/*! @{ */
-
 /*!
  * \brief A message cache, for use with \ref stasis_caching_topic.
  * \since 12
@@ -1090,6 +1074,10 @@ struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struc
  */
 struct ao2_container *stasis_cache_dump_all(struct stasis_cache *cache, struct stasis_message_type *type);
 
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
+ */
+
 /*!
  * \brief Object type code for multi user object snapshots
  */
@@ -1163,8 +1151,6 @@ void ast_multi_object_blob_single_channel_publish(struct ast_channel *chan, stru
 
 /*! @} */
 
-/*! @{ */
-
 /*!
  * \internal
  * \brief Log a message about invalid attempt to access a type.
@@ -1267,10 +1253,6 @@ void stasis_log_bad_type_access(const char *name);
                _priv_ ## name = NULL;          \
        })
 
-/*! @} */
-
-/*! @{ */
-
 /*!
  * \brief Initialize the Stasis subsystem.
  * \return 0 on success.
@@ -1279,10 +1261,6 @@ void stasis_log_bad_type_access(const char *name);
  */
 int stasis_init(void);
 
-/*! @} */
-
-/*! @{ */
-
 /*!
  * \internal
  * \brief called by stasis_init() for cache initialization.
@@ -1301,12 +1279,10 @@ int stasis_cache_init(void);
  */
 int stasis_config_init(void);
 
-/*! @} */
-
 /*!
  * \defgroup StasisTopicsAndMessages Stasis topics, and their messages.
  *
- * This group contains the topics, messages and corresponding message types
+ * \brief This group contains the topics, messages and corresponding message types
  * found within Asterisk.
  */
 

diff --git a/include/asterisk/stasis_test.h b/include/asterisk/stasis_test.h
index ad4020a08bacfc84c1a8076f9daead960dd0016e..d9df1c97f62617604e7f3c5c84b4325576e40cab 100644 (file)
--- a/include/asterisk/stasis_test.h
+++ b/include/asterisk/stasis_test.h
@@ -20,7 +20,8 @@
 #define _ASTERISK_STASIS_TEST_H
 
 /*!
- * \file \brief Test infrastructure for dealing with Stasis.
+ * \file
+ * \brief Test infrastructure for dealing with Stasis.
  *
  * \author David M. Lee, II <dlee@digium.com>
  *

diff --git a/main/sdp_srtp.c b/main/sdp_srtp.c
index 8c86f1407fc26d5cabeb2429dcdbdbcb6493d4a5..4ec9f810e4b465249abb6ead604154a255f0c663 100644 (file)
--- a/main/sdp_srtp.c
+++ b/main/sdp_srtp.c
@@ -16,7 +16,7 @@
  * at the top of the source tree.
  */
 
-/*! \file ast_sdp_crypto.c
+/*! \file
  *
  * \brief SRTP and SDP Security descriptions
  *

diff --git a/res/res_stasis_test.c b/res/res_stasis_test.c
index 9164293f5b4704974c60093c96f125b0ec590aa4..efdbc4b529fb2e6bb12222193a5d9dba1e0e0c7c 100644 (file)
--- a/res/res_stasis_test.c
+++ b/res/res_stasis_test.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test infrastructure for dealing with Stasis.
+ * \file
+ * \brief Test infrastructure for dealing with Stasis.
  *
  * \author David M. Lee, II <dlee@digium.com>
  */

diff --git a/tests/test_ari.c b/tests/test_ari.c
index 55f44321a32dba6a72c146eaa55d8a793b804431..efec810e172858b43e33e8dfc31eb2dd874e31f8 100644 (file)
--- a/tests/test_ari.c
+++ b/tests/test_ari.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test ARI API.
+ * \file
+ * \brief Test ARI API.
  * \author\verbatim David M. Lee, II <dlee@digium.com> \endverbatim
  *
  * \ingroup tests

diff --git a/tests/test_endpoints.c b/tests/test_endpoints.c
index d90cd3a05cbf94401ec2df771610c5b6c0c4c177..d1239037b8e0c8d6fddd620013e580ec32148282 100644 (file)
--- a/tests/test_endpoints.c
+++ b/tests/test_endpoints.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test endpoints.
+ * \file
+ * \brief Test endpoints.
  *
  * \author\verbatim David M. Lee, II <dlee@digium.com> \endverbatim
  *

diff --git a/tests/test_json.c b/tests/test_json.c
index 7080face27f7ad9be0787649f4acf255f4df6c78..9155781287ff1d763e27fa6e0a68dc9f00b0ae6e 100644 (file)
--- a/tests/test_json.c
+++ b/tests/test_json.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test JSON API.
+ * \file
+ * \brief Test JSON API.
  *
  * While some of these tests are actually testing our JSON library wrapper, the bulk of
  * them are exploratory tests to determine what the behavior of the underlying JSON

diff --git a/tests/test_optional_api.c b/tests/test_optional_api.c
index a89b46159b64c4468b5e2c33d210204db91f7901..f7809d32ba181350bbd9dd9fbea2ec40f4d50639 100644 (file)
--- a/tests/test_optional_api.c
+++ b/tests/test_optional_api.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test optional API.
+ * \file
+ * \brief Test optional API.
  *
  * This tests exercise the underlying implementation functions. Acutal usage
  * won't look anything like this; it would use the wrapper macros.

diff --git a/tests/test_res_stasis.c b/tests/test_res_stasis.c
index 7edc985e87bee9ed7cdc9133c4a6b7ce59fe060e..4e28d44c6368160a6caa5f6f691fe9eaa57bf9f9 100644 (file)
--- a/tests/test_res_stasis.c
+++ b/tests/test_res_stasis.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test Stasis Application API.
+ * \file
+ * \brief Test Stasis Application API.
  * \author\verbatim David M. Lee, II <dlee@digium.com> \endverbatim
  *
  * \ingroup tests

diff --git a/tests/test_stasis.c b/tests/test_stasis.c
index 7061b97b6c41d90c8fc8dddd44119b02700a8d6c..b5755c8430882854c08c21c769ad67ca001dd53c 100644 (file)
--- a/tests/test_stasis.c
+++ b/tests/test_stasis.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test Stasis message bus.
+ * \file
+ * \brief Test Stasis message bus.
  *
  * \author\verbatim David M. Lee, II <dlee@digium.com> \endverbatim
  *

diff --git a/tests/test_stasis_channels.c b/tests/test_stasis_channels.c
index f9bbb96211e338344300faae1841edd1a49882c5..fe320f29bca066c909b0eb85a7c440896b2e8326 100644 (file)
--- a/tests/test_stasis_channels.c
+++ b/tests/test_stasis_channels.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test Stasis Channel messages and objects
+ * \file
+ * \brief Test Stasis Channel messages and objects
  *
  * \author\verbatim Matt Jordan <mjordan@digium.com> \endverbatim
  *

diff --git a/tests/test_stasis_endpoints.c b/tests/test_stasis_endpoints.c
index 8e3907ffeadc9b6d2c5326da3deda2360004353c..848d86b1c500f2bcca3c2b48406b0496ab35199d 100644 (file)
--- a/tests/test_stasis_endpoints.c
+++ b/tests/test_stasis_endpoints.c
@@ -17,7 +17,8 @@
  */
 
 /*!
- * \file \brief Test endpoints.
+ * \file
+ * \brief Test endpoints.
  *
  * \author\verbatim David M. Lee, II <dlee@digium.com> \endverbatim
  *

diff --git a/utils/extconf.c b/utils/extconf.c
index baca11bf58dd6f8e2bc16eb148c4da4c67445353..4eaea3c2d374afe15d4f24fa46a413a7336d211f 100644 (file)
--- a/utils/extconf.c
+++ b/utils/extconf.c
@@ -18,7 +18,7 @@
 
 
 /*!
- * \file extconf
+ * \file
  * A condensation of the pbx_config stuff, to read into exensions.conf, and provide an interface to the data there,
  * for operations outside of asterisk. A huge, awful hack.
  *