[Asterisk-code-review] doxygen: Fix doxygen errors (asterisk[master])
Joshua Colp
asteriskteam at digium.com
Wed May 20 11:47:48 CDT 2015
Joshua Colp has submitted this change and it was merged.
Change subject: doxygen: Fix doxygen errors
......................................................................
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
---
M include/asterisk/event.h
M include/asterisk/rtp_engine.h
M include/asterisk/sem.h
M include/asterisk/stasis.h
M include/asterisk/stasis_test.h
M main/sdp_srtp.c
M res/res_stasis_test.c
M tests/test_ari.c
M tests/test_endpoints.c
M tests/test_json.c
M tests/test_optional_api.c
M tests/test_res_stasis.c
M tests/test_stasis.c
M tests/test_stasis_channels.c
M tests/test_stasis_endpoints.c
M utils/extconf.c
16 files changed, 32 insertions(+), 44 deletions(-)
Approvals:
Richard Mudgett: Looks good to me, but someone else must approve
Joshua Colp: Looks good to me, approved; Verified
diff --git a/include/asterisk/event.h b/include/asterisk/event.h
index 7eea058..dbc080d 100644
--- 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 a94cb42..c7f6511 100644
--- a/include/asterisk/rtp_engine.h
+++ b/include/asterisk/rtp_engine.h
@@ -2316,7 +2316,7 @@
*/
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 6d655d6..fcab82a 100644
--- 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 0b1b1e8..aa681e1 100644
--- 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_event *stasis_message_to_event(
struct stasis_message *message);
-/*! @} */
-
-/*! @{ */
-
/*!
* \brief A topic to which messages may be posted, and subscribers, well, subscribe
* \since 12
@@ -507,10 +501,6 @@
* \since 12.1.0
*/
void stasis_publish_sync(struct stasis_subscription *sub, struct stasis_message *message);
-
-/*! @} */
-
-/*! @{ */
/*!
* \brief Callback function type for Stasis subscriptions.
@@ -699,8 +689,6 @@
/*! @} */
-/*! @{ */
-
/*!
* \brief Pool for topic aggregation
*/
@@ -722,8 +710,6 @@
* \return \c NULL if the topic was not found and could not be allocated
*/
struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name);
-
-/*! @} */
/*! \addtogroup StasisTopicsAndMessages
* @{
@@ -756,8 +742,6 @@
struct stasis_message_type *stasis_cache_clear_type(void);
/*! @} */
-
-/*! @{ */
/*!
* \brief A message cache, for use with \ref stasis_caching_topic.
@@ -1090,6 +1074,10 @@
*/
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
*/
@@ -1162,8 +1150,6 @@
/*! @} */
-
-/*! @{ */
/*!
* \internal
@@ -1267,10 +1253,6 @@
_priv_ ## name = NULL; \
})
-/*! @} */
-
-/*! @{ */
-
/*!
* \brief Initialize the Stasis subsystem.
* \return 0 on success.
@@ -1278,10 +1260,6 @@
* \since 12
*/
int stasis_init(void);
-
-/*! @} */
-
-/*! @{ */
/*!
* \internal
@@ -1301,12 +1279,10 @@
*/
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 ad4020a..d9df1c9 100644
--- 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 at digium.com>
*
diff --git a/main/sdp_srtp.c b/main/sdp_srtp.c
index 8c86f14..4ec9f81 100644
--- 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 9164293..efdbc4b 100644
--- 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 at digium.com>
*/
diff --git a/tests/test_ari.c b/tests/test_ari.c
index 55f4432..efec810 100644
--- 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 at digium.com> \endverbatim
*
* \ingroup tests
diff --git a/tests/test_endpoints.c b/tests/test_endpoints.c
index d90cd3a..d123903 100644
--- 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 at digium.com> \endverbatim
*
diff --git a/tests/test_json.c b/tests/test_json.c
index 7080fac..9155781 100644
--- 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 a89b461..f7809d3 100644
--- 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 7edc985..4e28d44 100644
--- 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 at digium.com> \endverbatim
*
* \ingroup tests
diff --git a/tests/test_stasis.c b/tests/test_stasis.c
index 7061b97..b5755c8 100644
--- 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 at digium.com> \endverbatim
*
diff --git a/tests/test_stasis_channels.c b/tests/test_stasis_channels.c
index f9bbb96..fe320f2 100644
--- 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 at digium.com> \endverbatim
*
diff --git a/tests/test_stasis_endpoints.c b/tests/test_stasis_endpoints.c
index 8e3907f..848d86b 100644
--- 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 at digium.com> \endverbatim
*
diff --git a/utils/extconf.c b/utils/extconf.c
index baca11b..4eaea3c 100644
--- 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.
*
--
To view, visit https://gerrit.asterisk.org/489
To unsubscribe, visit https://gerrit.asterisk.org/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: Ia1415ffec6767e27233ae1cae5ed5970de5656d4
Gerrit-PatchSet: 1
Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Owner: Matt Jordan <mjordan at digium.com>
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
Gerrit-Reviewer: Matt Jordan <mjordan at digium.com>
Gerrit-Reviewer: Richard Mudgett <rmudgett at digium.com>
More information about the asterisk-code-review
mailing list