From c67a06a2ff87ffd1dd3607866d965ef3caabe232 Mon Sep 17 00:00:00 2001
From: "David M. Lee" <dlee@digium.com>
Date: Wed, 27 Mar 2013 21:52:43 +0000
Subject: [PATCH] Added a doxygen group for Stasis messages and topics

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@384201 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
 include/asterisk/app.h     |  6 +++++
 include/asterisk/channel.h | 48 +++++++++++++++++++++-----------------
 include/asterisk/stasis.h  | 31 +++++++++++++++++++-----
 3 files changed, 58 insertions(+), 27 deletions(-)

diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index 0505786e6a..d6ae5fe8b1 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -1120,6 +1120,10 @@ int stasis_publish_mwi_state_full(
 			int old_msgs,
 			struct ast_eid *eid);
 
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
+ */
+
 /*!
  * \brief The structure that contains MWI state
  * \since 12
@@ -1168,6 +1172,8 @@ struct stasis_caching_topic *stasis_mwi_topic_cached(void);
  */
 struct stasis_message_type *stasis_mwi_state_message(void);
 
+/*! @} */
+
 /*!
  * \brief Initialize the application core
  * \retval 0 Success
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index b60a92af85..30a05a1813 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -4104,6 +4104,31 @@ void ast_channel_dialed_causes_clear(const struct ast_channel *chan);
 
 struct ast_flags *ast_channel_flags(struct ast_channel *chan);
 
+/*!
+ * \since 12
+ * \brief Sets the variables to be stored in the \a manager_vars field of all
+ * snapshots.
+ * \param varc Number of variable names.
+ * \param vars Array of variable names.
+ */
+void ast_channel_set_manager_vars(size_t varc, char **vars);
+
+/*!
+ * \since 12
+ * \brief Gets the variables for a given channel, as specified by ast_channel_set_manager_vars().
+ *
+ * The returned variable list is an AO2 object, so ao2_cleanup() to free it.
+ *
+ * \param chan Channel to get variables for.
+ * \return List of channel variables.
+ * \return \c NULL on error
+ */
+struct varshead *ast_channel_get_manager_vars(struct ast_channel *chan);
+
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
+ */
+
 /*!
  * \since 12
  * \brief Structure representing a snapshot of channel state.
@@ -4155,27 +4180,6 @@ struct ast_channel_snapshot {
  */
 struct ast_channel_snapshot *ast_channel_snapshot_create(struct ast_channel *chan);
 
-/*!
- * \since 12
- * \brief Sets the variables to be stored in the \a manager_vars field of all
- * snapshots.
- * \param varc Number of variable names.
- * \param vars Array of variable names.
- */
-void ast_channel_set_manager_vars(size_t varc, char **vars);
-
-/*!
- * \since 12
- * \brief Gets the variables for a given channel, as specified by ast_channel_set_manager_vars().
- *
- * The returned variable list is an AO2 object, so ao2_cleanup() to free it.
- *
- * \param chan Channel to get variables for.
- * \return List of channel variables.
- * \return \c NULL on error
- */
-struct varshead *ast_channel_get_manager_vars(struct ast_channel *chan);
-
 /*!
  * \since 12
  * \brief Message type for \ref ast_channel_snapshot.
@@ -4261,6 +4265,8 @@ const char *ast_channel_blob_type(struct ast_channel_blob *obj);
 struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
 					       struct ast_json *blob);
 
+/*! @} */
+
 /*!
  * \since 12
  * \brief Publish a \ref ast_channel_varset for a channel.
diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h
index c8523dc50c..936a75d539 100644
--- a/include/asterisk/stasis.h
+++ b/include/asterisk/stasis.h
@@ -356,6 +356,10 @@ int stasis_subscription_is_subscribed(const struct stasis_subscription *sub);
  */
 int stasis_subscription_final_message(struct stasis_subscription *sub, struct stasis_message *msg);
 
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
+ */
+
 /*!
  * \brief Holds details about changes to subscriptions for the specified topic
  * \since 12
@@ -375,6 +379,8 @@ struct stasis_subscription_change {
  */
 struct stasis_message_type *stasis_subscription_change(void);
 
+/*! @} */
+
 /*!
  * \brief Pool for topic aggregation
  */
@@ -398,13 +404,9 @@ struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool,
 
 /*! @} */
 
-/*! @{ */
-
-/*!
- * \brief A topic wrapper, which caches certain messages.
- * \since 12
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
  */
-struct stasis_caching_topic;
 
 /*!
  * \brief Message type for cache update messages.
@@ -438,6 +440,16 @@ struct stasis_cache_update {
  */
 struct stasis_message *stasis_cache_clear_create(struct stasis_message_type *type, const char *id);
 
+/*! @} */
+
+/*! @{ */
+
+/*!
+ * \brief A topic wrapper, which caches certain messages.
+ * \since 12
+ */
+struct stasis_caching_topic;
+
 /*!
  * \brief Callback extract a unique identity from a snapshot message.
  *
@@ -533,4 +545,11 @@ int stasis_cache_init(void);
 
 /*! @} */
 
+/*!
+ * \defgroup StasisTopicsAndMessages Stasis topics, and their messages.
+ *
+ * This group contains the topics, messages and corresponding message types
+ * found within Asterisk.
+ */
+
 #endif /* _ASTERISK_STASIS_H */