[Asterisk-code-review] stasis: Fix for Doxygen. (asterisk[19])
Friendly Automation
asteriskteam at digium.com
Thu Nov 18 13:44:34 CST 2021
Friendly Automation has submitted this change. ( https://gerrit.asterisk.org/c/asterisk/+/17490 )
Change subject: stasis: Fix for Doxygen.
......................................................................
stasis: Fix for Doxygen.
ASTERISK-29750
Change-Id: Iea50173e785b2e9d49bc24c0af7111cfd96d44a9
---
M include/asterisk/stasis.h
M include/asterisk/stasis_app.h
M include/asterisk/stasis_app_device_state.h
M include/asterisk/stasis_app_playback.h
M include/asterisk/stasis_app_recording.h
M include/asterisk/stasis_app_snoop.h
M include/asterisk/stasis_bridges.h
M include/asterisk/stasis_channels.h
M include/asterisk/stasis_internal.h
M include/asterisk/stasis_message_router.h
M include/asterisk/stasis_system.h
M include/asterisk/stasis_test.h
M main/stasis.c
M main/stasis_bridges.c
M main/stasis_cache.c
M main/stasis_state.c
M res/res_stasis_snoop.c
M res/stasis/app.c
M res/stasis/app.h
M res/stasis/control.h
M res/stasis/messaging.h
M res/stasis/stasis_bridge.c
M res/stasis/stasis_bridge.h
M res/stasis_recording/stored.c
24 files changed, 232 insertions(+), 263 deletions(-)
Approvals:
Kevin Harwell: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h
index e18b886..af9a67c 100644
--- a/include/asterisk/stasis.h
+++ b/include/asterisk/stasis.h
@@ -65,7 +65,7 @@
*
* \par stasis_topic
*
- * A \ref stasis_topic is an object to which \ref stasis_subscriber's may be
+ * A \ref stasis_topic is an object to which stasis_topic_subscriber's may be
* subscribed, and \ref stasis_message's may be published. Any message published
* to the topic is dispatched to all of its subscribers. The topic itself may be
* named, which is useful in debugging.
@@ -106,7 +106,7 @@
* cache may be shared amongst different message types, such a usage is probably
* not a good idea.
*
- * The \ref stasis_cache can only be written to by \ref stasis_caching_topics.
+ * The \ref stasis_cache can only be written to by \ref stasis_caching_topic.
* It's a thread safe container, so freely use the stasis_cache_get() and
* stasis_cache_dump() to query the cache.
*
@@ -125,7 +125,7 @@
* The \ref stasis_cache object is a normal AO2 managed object, which can be
* release with ao2_cleanup().
*
- * \par stasis_subscriber
+ * \par stasis_topic_subscriber
*
* Any topic may be subscribed to by simply providing stasis_subscribe() the
* \ref stasis_topic to subscribe to, a handler function and \c void pointer to
@@ -247,8 +247,7 @@
* \param sanitize Snapshot sanitization callback.
*
* \return Newly allocated JSON message.
- * \return \c NULL on error.
- * \return \c NULL if JSON format is not supported.
+ * \retval NULL if JSON format is not supported.
*/
struct ast_json *(*to_json)(struct stasis_message *message, const struct stasis_message_sanitizer *sanitize);
@@ -260,8 +259,7 @@
*
* \param message Message to convert to AMI string.
* \return Newly allocated \ref ast_manager_event_blob.
- * \return \c NULL on error.
- * \return \c NULL if AMI format is not supported.
+ * \retval NULL if AMI format is not supported.
*/
struct ast_manager_event_blob *(*to_ami)(
struct stasis_message *message);
@@ -275,8 +273,7 @@
*
* \param message Message to convert to an \ref ast_event.
* \return Newly allocated \ref ast_event.
- * \return \c NULL on error.
- * \return \c NULL if AMI format is not supported.
+ * \retval NULL if AMI format is not supported.
*/
struct ast_event *(*to_event)(
struct stasis_message *message);
@@ -337,7 +334,7 @@
* \brief Gets the name of a given message type
* \param type The type to get.
* \return Name of the type.
- * \return \c NULL if \a type is \c NULL.
+ * \retval NULL if \a type is \c NULL.
* \since 12
*/
const char *stasis_message_type_name(const struct stasis_message_type *type);
@@ -379,7 +376,7 @@
* \param data Immutable data that is the actual contents of the message
*
* \return New message
- * \return \c NULL on error
+ * \retval NULL on error
*
* \since 12
*/
@@ -404,7 +401,7 @@
* any remote entities publishing to a mailbox.
*
* \retval New message
- * \retval \c NULL on error
+ * \retval NULL on error
*
* \since 12.2.0
*/
@@ -417,7 +414,7 @@
* \param msg Message to get eid.
*
* \retval Entity id of \a msg
- * \retval \c NULL if \a msg is an aggregate or \a msg is \c NULL.
+ * \retval NULL if \a msg is an aggregate or \a msg is \c NULL.
*/
const struct ast_eid *stasis_message_eid(const struct stasis_message *msg);
@@ -425,7 +422,7 @@
* \brief Get the message type for a \ref stasis_message.
* \param msg Message to type
* \return Type of \a msg
- * \return \c NULL if \a msg is \c NULL.
+ * \retval NULL if \a msg is \c NULL.
* \since 12
*/
struct stasis_message_type *stasis_message_type(const struct stasis_message *msg);
@@ -434,7 +431,7 @@
* \brief Get the data contained in a message.
* \param msg Message.
* \return Immutable data pointer
- * \return \c NULL if msg is \c NULL.
+ * \retval NULL if msg is \c NULL.
* \since 12
*/
void *stasis_message_data(const struct stasis_message *msg);
@@ -443,7 +440,7 @@
* \brief Get the time when a message was created.
* \param msg Message.
* \return Pointer to the \a timeval when the message was created.
- * \return \c NULL if msg is \c NULL.
+ * \retval NULL if msg is \c NULL.
* \since 12
*/
const struct timeval *stasis_message_timestamp(const struct stasis_message *msg);
@@ -458,8 +455,7 @@
* \param sanitize Snapshot sanitization callback.
*
* \return Newly allocated string with JSON message.
- * \return \c NULL on error.
- * \return \c NULL if JSON format is not supported.
+ * \retval NULL if JSON format is not supported.
*/
struct ast_json *stasis_message_to_json(struct stasis_message *msg, struct stasis_message_sanitizer *sanitize);
@@ -470,8 +466,7 @@
* be ao2_cleanup()'ed.
*
* \param msg Message to convert to AMI.
- * \return \c NULL on error.
- * \return \c NULL if AMI format is not supported.
+ * \retval NULL if AMI format is not supported.
*/
struct ast_manager_event_blob *stasis_message_to_ami(struct stasis_message *msg);
@@ -492,8 +487,7 @@
* be disposed of via \ref ast_event_destroy.
*
* \param msg Message to convert to AMI.
- * \return \c NULL on error.
- * \return \c NULL if AMI format is not supported.
+ * \retval NULL if AMI format is not supported.
*/
struct ast_event *stasis_message_to_event(struct stasis_message *msg);
@@ -507,7 +501,7 @@
* \brief Create a new topic.
* \param name Name of the new topic.
* \return New topic instance.
- * \return \c NULL on error.
+ * \retval NULL on error.
* \since 12
*
* \note There is no explicit ability to unsubscribe all subscribers
@@ -515,7 +509,8 @@
* the last subscriber unsubscribes itself even if there is no
* publisher.
*
- * \note Topic names should be in the form of <subsystem>:<functionality>[/<object>]
+ * \note Topic names should be in the form of
+ * \verbatim <subsystem>:<functionality>[/<object>] \endverbatim
*/
struct stasis_topic *stasis_topic_create(const char *name);
@@ -524,7 +519,7 @@
* \param name Name of the new topic.
* \param detail Detail description of the new topic. i.e. "Queue main topic for subscribing every queue event"
* \return New topic instance.
- * \return \c NULL on error.
+ * \retval NULL on error.
*
* \note There is no explicit ability to unsubscribe all subscribers
* from a topic and destroy it. As a result the topic can persist until
@@ -538,7 +533,7 @@
* \brief Get a topic of the given name.
* \param name Topic's name.
* \return Name of the topic.
- * \return \c NULL on error or not exist.
+ * \retval NULL on error or not exist.
*
* \note This SHOULD NOT be used in normal operation for publishing messages.
*/
@@ -548,7 +543,7 @@
* \brief Return the uniqueid of a topic.
* \param topic Topic.
* \return Uniqueid of the topic.
- * \return \c NULL if topic is \c NULL.
+ * \retval NULL if topic is \c NULL.
*/
const char *stasis_topic_uniqueid(const struct stasis_topic *topic);
@@ -556,7 +551,7 @@
* \brief Return the name of a topic.
* \param topic Topic.
* \return Name of the topic.
- * \return \c NULL if topic is \c NULL.
+ * \retval NULL if topic is \c NULL.
*/
const char *stasis_topic_name(const struct stasis_topic *topic);
@@ -564,7 +559,7 @@
* \brief Return the detail of a topic.
* \param topic Topic.
* \return Detail of the topic.
- * \return \c NULL if topic is \c NULL.
+ * \retval NULL if topic is \c NULL.
* \since 12
*/
const char *stasis_topic_detail(const struct stasis_topic *topic);
@@ -598,7 +593,7 @@
* The caller of stasis_publish_sync will block until the specified
* subscriber completes handling of the message.
*
- * All other subscribers to the topic the \ref stasis_subpscription
+ * All other subscribers to the topic the \ref stasis_subscription
* is subscribed to are also delivered the message; this delivery however
* happens asynchronously.
*
@@ -609,6 +604,7 @@
/*!
* \brief Callback function type for Stasis subscriptions.
* \param data Data field provided with subscription.
+ * \param sub Subscription published on.
* \param message Published message.
* \since 12
*/
@@ -639,8 +635,9 @@
* \param topic Topic to subscribe to.
* \param callback Callback function for subscription messages.
* \param data Data to be passed to the callback, in addition to the message.
+ * \param file, lineno, func
* \return New \ref stasis_subscription object.
- * \return \c NULL on error.
+ * \retval NULL on error.
* \since 12
*
* \note This callback will receive a callback with a message indicating it
@@ -669,8 +666,9 @@
* \param topic Topic to subscribe to.
* \param callback Callback function for subscription messages.
* \param data Data to be passed to the callback, in addition to the message.
+ * \param file, lineno, func
* \return New \ref stasis_subscription object.
- * \return \c NULL on error.
+ * \retval NULL on error.
* \since 12.8.0
*
* \note This callback will receive a callback with a message indicating it
@@ -768,7 +766,7 @@
* delivery of the final message.
*
* \param subscription Subscription to cancel.
- * \return \c NULL for convenience
+ * \retval NULL for convenience
* \since 12
*/
struct stasis_subscription *stasis_unsubscribe(
@@ -823,7 +821,7 @@
* a function in a shared module that no longer exists).
*
* \param subscription Subscription to cancel.
- * \return \c NULL for convenience
+ * \retval NULL for convenience
* \since 12
*/
struct stasis_subscription *stasis_unsubscribe_and_join(
@@ -841,7 +839,7 @@
* \param from_topic Topic to forward.
* \param to_topic Destination topic of forwarded messages.
* \return New forwarding subscription.
- * \return \c NULL on error.
+ * \retval NULL on error.
* \since 12
*/
struct stasis_forward *stasis_forward_all(struct stasis_topic *from_topic,
@@ -913,7 +911,7 @@
* \brief Create a topic pool that routes messages from dynamically generated topics to the given topic
* \param pooled_topic Topic to which messages will be routed
* \return the new stasis_topic_pool
- * \return \c NULL on failure
+ * \retval NULL on failure
*/
struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_topic);
@@ -922,7 +920,7 @@
* \param pool Pool for which to get the topic
* \param topic_name Name of the topic to get
* \return The already stored or newly allocated topic
- * \return \c NULL if the topic was not found and could not be allocated
+ * \retval 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);
@@ -931,7 +929,7 @@
*
* \param pool Pool from which to delete the topic
* \param topic_name Name of the topic to delete in the form of
- * <pool_topic_name>/<topic_name> or just <topic_name>
+ * \verbatim [<pool_topic_name>/]<topic_name> \endverbatim
*
* \since 13.24
* \since 15.6
@@ -1005,7 +1003,7 @@
*
* \param message Message to extract id from.
* \return String representing the snapshot's id.
- * \return \c NULL if the message_type of the message isn't a handled snapshot.
+ * \retval NULL if the message_type of the message isn't a handled snapshot.
* \since 12
*/
typedef const char *(*snapshot_get_id)(struct stasis_message *message);
@@ -1115,8 +1113,8 @@
*
* \param id_fn Callback to extract the id from a snapshot message.
*
- * \retval New cache indexed by \a id_fn.
- * \retval \c NULL on error
+ * \return New cache indexed by \a id_fn.
+ * \retval NULL on error
*
* \since 12
*/
@@ -1141,8 +1139,8 @@
* MWI message is the old/new MWI counts accumulated from the local and
* any remote entities publishing to a mailbox.
*
- * \retval New cache indexed by \a id_fn.
- * \retval \c NULL on error
+ * \return New cache indexed by \a id_fn.
+ * \retval NULL on error
*
* \since 12.2.0
*/
@@ -1162,7 +1160,7 @@
* \param cache Backend cache in which to keep snapshots.
* \return New topic which changes snapshot messages to stasis_cache_update()
* messages, and forwards all other messages from the original topic.
- * \return \c NULL on error
+ * \retval NULL on error
* \since 12
*/
struct stasis_caching_topic *stasis_caching_topic_create(
@@ -1175,7 +1173,7 @@
* stasis_subscription_final_message() is received.
*
* \param caching_topic Caching topic to unsubscribe
- * \return \c NULL for convenience
+ * \retval NULL for convenience
* \since 12
*/
struct stasis_caching_topic *stasis_caching_unsubscribe(
@@ -1189,7 +1187,7 @@
* opposed to stasis_caching_unsubscribe().
*
* \param caching_topic Caching topic to unsubscribe
- * \return \c NULL for convenience
+ * \retval NULL for convenience
* \since 12
*/
struct stasis_caching_topic *stasis_caching_unsubscribe_and_join(
@@ -1200,7 +1198,7 @@
* \param caching_topic The caching topic.
* \return The topic that publishes cache update events, along with passthrough
* events from the underlying topic.
- * \return \c NULL if \a caching_topic is \c NULL.
+ * \retval NULL if \a caching_topic is \c NULL.
* \since 12
*/
struct stasis_topic *stasis_caching_get_topic(
@@ -1251,7 +1249,7 @@
*
* \return Message which, when sent to a \ref stasis_caching_topic, will clear
* the item from the cache.
- * \return \c NULL on error.
+ * \retval NULL on error.
* \since 12
*/
struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
@@ -1265,8 +1263,8 @@
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
*
- * \retval Message from the cache.
- * \retval \c NULL if message is not found.
+ * \return Message from the cache.
+ * \retval NULL if message is not found.
*
* \since 12
*/
@@ -1289,8 +1287,8 @@
* MWI message is the old/new MWI counts accumulated from the local and
* any remote entities publishing to a mailbox.
*
- * \retval Message from the cache.
- * \retval \c NULL if message is not found.
+ * \return Message from the cache.
+ * \retval NULL if message is not found.
*
* \since 12.2.0
*/
@@ -1304,8 +1302,8 @@
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
*
- * \retval Container of matching items found.
- * \retval \c NULL if error.
+ * \return Container of matching items found.
+ * \retval NULL if error.
*/
struct ao2_container *stasis_cache_get_all(struct stasis_cache *cache, struct stasis_message_type *type, const char *id);
@@ -1315,8 +1313,8 @@
* \param cache The cache to query.
* \param type Type of message to dump (any type if \c NULL).
*
- * \retval ao2_container containing all matches (must be unreffed by caller)
- * \retval \c NULL on allocation error
+ * \return ao2_container containing all matches (must be unreffed by caller)
+ * \retval NULL on allocation error
*
* \since 12
*/
@@ -1330,8 +1328,8 @@
* \param type Type of message to dump (any type if \c NULL).
* \param eid Specific entity id to retrieve. NULL for aggregate.
*
- * \retval ao2_container containing all matches (must be unreffed by caller)
- * \retval \c NULL on allocation error
+ * \return ao2_container containing all matches (must be unreffed by caller)
+ * \retval NULL on allocation error
*/
struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struct stasis_message_type *type, const struct ast_eid *eid);
@@ -1342,8 +1340,8 @@
* \param cache The cache to query.
* \param type Type of message to dump (any type if \c NULL).
*
- * \retval ao2_container containing all matches (must be unreffed by caller)
- * \retval \c NULL on allocation error
+ * \return ao2_container containing all matches (must be unreffed by caller)
+ * \retval NULL on allocation error
*/
struct ao2_container *stasis_cache_dump_all(struct stasis_cache *cache, struct stasis_message_type *type);
@@ -1399,8 +1397,6 @@
* \param multi The multi object blob previously created
* \param type Type code for the object such as channel, bridge, etc.
* \param object Snapshot object of the type supplied to typename
- *
- * \return Nothing
*/
void ast_multi_object_blob_add(struct ast_multi_object_blob *multi, enum stasis_user_multi_object_snapshot_type type, void *object);
@@ -1416,8 +1412,6 @@
* \param chan The channel to snapshot and publish event to
* \param type The message type
* \param blob A json blob to publish with the snapshot
- *
- * \return Nothing
*/
void ast_multi_object_blob_single_channel_publish(struct ast_channel *chan, struct stasis_message_type *type, struct ast_json *blob);
diff --git a/include/asterisk/stasis_app.h b/include/asterisk/stasis_app.h
index 285d54a..9a01ef3 100644
--- a/include/asterisk/stasis_app.h
+++ b/include/asterisk/stasis_app.h
@@ -71,7 +71,7 @@
* \brief Gets the names of all registered Stasis applications.
*
* \return \c ast_str_container of container names.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ao2_container *stasis_app_get_all(void);
@@ -81,7 +81,7 @@
* \param name The name of the registered Stasis application
*
* \return \c stasis_app on success.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app *stasis_app_get_by_name(const char *name);
@@ -154,7 +154,7 @@
* \param app The application.
*
* \return JSON representation of app with given name.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_json *stasis_app_object_to_json(struct stasis_app *app);
@@ -164,7 +164,7 @@
* \param app_name Name of the application.
*
* \return JSON representation of app with given name.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_json *stasis_app_to_json(const char *app_name);
@@ -452,8 +452,6 @@
* \since 13.9.0
*
* \param control Control object to flush command queue.
- *
- * \return Nothing
*/
void stasis_app_control_flush_queue(struct stasis_app_control *control);
@@ -463,7 +461,7 @@
* \param control Control object.
*
* \return Uniqueid of the associate channel.
- * \return \c NULL if \a control is \c NULL.
+ * \retval NULL if \a control is \c NULL.
*/
const char *stasis_app_control_get_channel_id(
const struct stasis_app_control *control);
@@ -649,7 +647,7 @@
* \param control Control for \c res_stasis.
*
* \return Most recent snapshot. ao2_cleanup() when done.
- * \return \c NULL if channel isn't in cache.
+ * \retval NULL if channel isn't in cache.
*/
struct ast_channel_snapshot *stasis_app_control_get_snapshot(
const struct stasis_app_control *control);
@@ -690,7 +688,7 @@
* \param id Optional Unique ID to give to the bridge
*
* \return New bridge.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_bridge *stasis_app_bridge_create(const char *type, const char *name, const char *id);
@@ -702,7 +700,7 @@
* \param id Optional Unique ID to give to the bridge
*
* \return New bridge.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_bridge *stasis_app_bridge_create_invisible(const char *type, const char *name, const char *id);
@@ -754,6 +752,7 @@
*
* \param bridge Bridge we are adding the playback channel for
* \param chan Channel being added as a playback channel (must be ;1)
+ * \param control The app control structure for the playback channel
*
* \retval -1 failed to add channel for any reason
* \retval 0 on success
@@ -842,7 +841,7 @@
* \brief Set whether COLP frames should be generated when joining the bridge
*
* \param control Control whose channel should have its COLP frames inhibited when bridged
- * \param mute Whether COLP frames should be generated (0) or not (1).
+ * \param inhibit_colp Whether COLP frames should be generated (0) or not (1).
*/
void stasis_app_control_inhibit_colp_in_bridge(
struct stasis_app_control *control, int inhibit_colp);
@@ -858,7 +857,7 @@
* \param control Control object for the channel to query.
*
* \return Associated \ref ast_bridge.
- * \return \c NULL if not associated with a bridge.
+ * \retval NULL if not associated with a bridge.
*/
struct ast_bridge *stasis_app_get_bridge(struct stasis_app_control *control);
@@ -866,9 +865,6 @@
* \brief Destroy the bridge.
*
* \param bridge_id Uniqueid of bridge to be destroyed
- *
- * \retval non-zero on failure
- * \retval zero on success
*/
void stasis_app_bridge_destroy(const char *bridge_id);
@@ -882,7 +878,7 @@
/*!
* \brief Indicate that this channel has had a StasisEnd published for it
*
- * \param The channel that is exiting Stasis.
+ * \param chan The channel that is exiting Stasis.
*/
void stasis_app_channel_set_stasis_end_published(struct ast_channel *chan);
diff --git a/include/asterisk/stasis_app_device_state.h b/include/asterisk/stasis_app_device_state.h
index 2bc521a..e01ac4a 100644
--- a/include/asterisk/stasis_app_device_state.h
+++ b/include/asterisk/stasis_app_device_state.h
@@ -85,7 +85,7 @@
*
* \param name the name of the ARI controlled device
*
- * \returna stasis device state application result.
+ * \return stasis device state application result.
*/
enum stasis_device_state_result stasis_app_device_state_delete(
const char *name);
diff --git a/include/asterisk/stasis_app_playback.h b/include/asterisk/stasis_app_playback.h
index ab49b09..716e950 100644
--- a/include/asterisk/stasis_app_playback.h
+++ b/include/asterisk/stasis_app_playback.h
@@ -97,7 +97,7 @@
* \param offsetms Number of milliseconds to skip before playing.
* \param id ID to assign the new playback or NULL for default.
* \return Playback control object.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app_playback *stasis_app_control_play_uri(
struct stasis_app_control *control, const char **media,
@@ -119,7 +119,7 @@
*
* \param playback Playback control object.
* \return \a playback's id.
- * \return \c NULL if \a playback ic \c NULL
+ * \retval NULL if \a playback ic \c NULL
*/
const char *stasis_app_playback_get_id(
struct stasis_app_playback *playback);
@@ -129,7 +129,7 @@
*
* \param id Id of the playback object to find.
* \return Associated \ref stasis_app_playback object.
- * \return \c NULL if \a id not found.
+ * \retval NULL if \a id not found.
*/
struct stasis_app_playback *stasis_app_playback_find_by_id(const char *id);
@@ -138,8 +138,8 @@
*
* \param playback The playback object to convert to JSON
*
- * \retval \c NULL on error
- * \retval A JSON object on success
+ * \retval NULL on error
+ * \return A JSON object on success
*/
struct ast_json *stasis_app_playback_to_json(
const struct stasis_app_playback *playback);
@@ -153,8 +153,8 @@
* \brief Controls the media for a given playback operation.
*
* \param playback Playback control object.
- * \param control Media control operation.
- * \return \c STASIS_PLAYBACK_OPER_OK on success.
+ * \param operation Media control operation.
+ * \retval STASIS_PLAYBACK_OPER_OK on success.
* \return \ref stasis_playback_oper_results indicating failure.
*/
enum stasis_playback_oper_results stasis_app_playback_operation(
diff --git a/include/asterisk/stasis_app_recording.h b/include/asterisk/stasis_app_recording.h
index bded306..1796095 100644
--- a/include/asterisk/stasis_app_recording.h
+++ b/include/asterisk/stasis_app_recording.h
@@ -43,7 +43,7 @@
*
* \param recording Recording to query.
* \return Absolute path to the recording file, without the extension.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
const char *stasis_app_stored_recording_get_file(
struct stasis_app_stored_recording *recording);
@@ -55,7 +55,7 @@
* \param recording Recording to query.
*
* \return Absolute path to the recording file, with the extension.
- * \return \c NULL on error
+ * \retval NULL on error
*/
const char *stasis_app_stored_recording_get_filename(
struct stasis_app_stored_recording *recording);
@@ -67,7 +67,7 @@
* \param recording Recording to query.
*
* \return The extension associated with this recording.
- * \return \c NULL on error
+ * \retval NULL on error
*/
const char *stasis_app_stored_recording_get_extension(
struct stasis_app_stored_recording *recording);
@@ -77,7 +77,7 @@
*
* \param recording Recording to convert.
* \return JSON representation.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_json *stasis_app_stored_recording_to_json(
struct stasis_app_stored_recording *recording);
@@ -86,7 +86,7 @@
* \brief Find all stored recordings on disk.
*
* \return Container of \ref stasis_app_stored_recording objects.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ao2_container *stasis_app_stored_recording_find_all(void);
@@ -95,7 +95,7 @@
*
* \param name Name of the recording.
* \return New recording object.
- * \return \c NULL if recording is not found. \c errno is set to indicate why
+ * \retval NULL if recording is not found. \c errno is set to indicate why
* - \c ENOMEM - out of memeory
* - \c EACCES - file permissions (or recording is outside the config dir)
* - Any of the error codes for stat(), opendir(), readdir()
@@ -202,7 +202,7 @@
* \param name Name of the recording.
* \param format Format to record in.
* \return Newly allocated options object.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app_recording_options *stasis_app_recording_options_create(
const char *name, const char *format);
@@ -212,9 +212,9 @@
*
* \param str String to parse.
* \return DTMF value to terminate on.
- * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
- * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
- * \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
+ * \retval STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF.
+ * \retval STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF.
+ * \retval STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid.
*/
char stasis_app_recording_termination_parse(const char *str);
@@ -242,7 +242,7 @@
* \param control Control for \c res_stasis.
* \param options Recording options.
* \return Recording control object.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app_recording *stasis_app_control_record(
struct stasis_app_control *control,
@@ -262,7 +262,7 @@
*
* \param recording Recording control object.
* \return \a recording's name.
- * \return \c NULL if \a recording ic \c NULL
+ * \retval NULL if \a recording ic \c NULL
*/
const char *stasis_app_recording_get_name(
struct stasis_app_recording *recording);
@@ -272,7 +272,7 @@
*
* \param name Name of the recording object to find.
* \return Associated \ref stasis_app_recording object.
- * \return \c NULL if \a name not found.
+ * \retval NULL if \a name not found.
*/
struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name);
@@ -281,7 +281,7 @@
*
* \param recording Recording to conver.
* \return JSON model.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_json *stasis_app_recording_to_json(
const struct stasis_app_recording *recording);
@@ -302,8 +302,8 @@
* \brief Controls the media for a given recording operation.
*
* \param recording Recording control object.
- * \param control Media control operation.
- * \return \c STASIS_APP_RECORDING_OPER_OK on success.
+ * \param operation Media control operation.
+ * \retval STASIS_APP_RECORDING_OPER_OK on success.
* \return \ref stasis_app_recording_oper_results indicating failure.
*/
enum stasis_app_recording_oper_results stasis_app_recording_operation(
diff --git a/include/asterisk/stasis_app_snoop.h b/include/asterisk/stasis_app_snoop.h
index c261a88..c9dc933 100644
--- a/include/asterisk/stasis_app_snoop.h
+++ b/include/asterisk/stasis_app_snoop.h
@@ -50,8 +50,9 @@
* \param whisper Direction of media that should be whispered into.
* \param app Stasis application to execute on the snoop channel.
* \param app_args Stasis application arguments.
- * \return Snoop channel. ast_channel_unref() when done.
- * \return \c NULL if snoop channel couldn't be created.
+ * \param snoop_id
+ * \return ast_channel ast_channel_unref() when done.
+ * \retval NULL if snoop channel couldn't be created.
*/
struct ast_channel *stasis_app_control_snoop(struct ast_channel *chan,
enum stasis_app_snoop_direction spy, enum stasis_app_snoop_direction whisper,
diff --git a/include/asterisk/stasis_bridges.h b/include/asterisk/stasis_bridges.h
index 3d6d2b2..a064f02 100644
--- a/include/asterisk/stasis_bridges.h
+++ b/include/asterisk/stasis_bridges.h
@@ -45,7 +45,7 @@
*
* \param bridge The bridge from which to generate a snapshot
*
- * \retval AO2 refcounted snapshot on success
+ * \return AO2 refcounted snapshot on success
* \retval NULL on error
*/
struct ast_bridge_snapshot *ast_bridge_snapshot_create(struct ast_bridge *bridge);
@@ -54,7 +54,7 @@
* \since 12
* \brief Message type for \ref ast_bridge_snapshot.
*
- * \retval Message type for \ref ast_bridge_snapshot.
+ * \return Message type for \ref ast_bridge_snapshot.
*/
struct stasis_message_type *ast_bridge_snapshot_type(void);
@@ -66,7 +66,7 @@
*
* \param bridge Bridge for which to get a topic or \c NULL.
*
- * \retval Topic for bridge's events.
+ * \return Topic for bridge's events.
* \retval ast_bridge_topic_all() if \a bridge is \c NULL.
*/
struct stasis_topic *ast_bridge_topic(struct ast_bridge *bridge);
@@ -74,7 +74,7 @@
/*!
* \since 12
* \brief A topic which publishes the events for all bridges.
- * \retval Topic for all bridge events.
+ * \return Topic for all bridge events.
*/
struct stasis_topic *ast_bridge_topic_all(void);
@@ -98,7 +98,7 @@
* \since 12
* \brief Message type for \ref ast_bridge_merge_message.
*
- * \retval Message type for \ref ast_bridge_merge_message.
+ * \return Message type for \ref ast_bridge_merge_message.
*/
struct stasis_message_type *ast_bridge_merge_message_type(void);
@@ -131,17 +131,17 @@
/*!
* \since 12
- * \brief Message type for \ref channel enter bridge blob messages.
+ * \brief Message type for \ref ast_channel enter bridge blob messages.
*
- * \retval Message type for \ref channel enter bridge blob messages.
+ * \return Message type for \ref ast_channel enter bridge blob messages.
*/
struct stasis_message_type *ast_channel_entered_bridge_type(void);
/*!
* \since 12
- * \brief Message type for \ref channel leave bridge blob messages.
+ * \brief Message type for \ref ast_channel leave bridge blob messages.
*
- * \retval Message type for \ref channel leave bridge blob messages.
+ * \return Message type for \ref ast_channel leave bridge blob messages.
*/
struct stasis_message_type *ast_channel_left_bridge_type(void);
@@ -156,10 +156,12 @@
* \pre bridge is locked.
* \pre No channels are locked.
*
+ * \param type
* \param bridge Channel blob is associated with, or NULL for global/all bridges.
+ * \param chan The channel that started the bridge
* \param blob JSON object representing the data.
* \return \ref ast_bridge_blob message.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct stasis_message *ast_bridge_blob_create(struct stasis_message_type *type,
struct ast_bridge *bridge,
@@ -178,11 +180,12 @@
* \pre bridge is locked.
* \pre No channels are locked.
*
+ * \param type
* \param bridge_snapshot Bridge snapshot
- * \param channel_snapshot Channel snapshot
+ * \param chan_snapshot Channel snapshot
* \param blob JSON object representing the data.
* \return \ref ast_bridge_blob message.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct stasis_message *ast_bridge_blob_create_from_snapshots(struct stasis_message_type *type,
struct ast_bridge_snapshot *bridge_snapshot,
@@ -222,7 +225,7 @@
* \param sanitize The message sanitizer to use on the snapshot
*
* \return JSON object representing bridge snapshot.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct ast_json *ast_bridge_snapshot_to_json(const struct ast_bridge_snapshot *snapshot,
const struct stasis_message_sanitizer *sanitize);
@@ -239,7 +242,7 @@
* \since 12
* \brief Message type for \ref ast_blind_transfer_message.
*
- * \retval Message type for \ref ast_blind_transfer_message.
+ * \return Message type for \ref ast_blind_transfer_message.
*/
struct stasis_message_type *ast_blind_transfer_type(void);
@@ -270,9 +273,8 @@
*
* \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
* \param transferer The transferer's channel that is bridged to the transferee
- * \param bridge The bridge the transferer and transferee are in
- * \param context The destination context for the blind transfer
* \param exten The destination extension for the blind transfer
+ * \param context The destination context for the blind transfer
*
* \retval NULL Failure to allocate or create snapshots
* \retval non-NULL The created blind transfer message
@@ -285,16 +287,7 @@
*
* \pre Bridges involved are locked. Channels involved are not locked.
*
- * \param is_external Whether the blind transfer was initiated externally (e.g. via AMI or native protocol)
- * \param result The success or failure of the transfer
- * \param to_transferee The bridge between the transferer and transferee plus the transferer channel
- * \param context The destination context for the blind transfer
- * \param exten The destination extension for the blind transfer
- * \param transferee_channel If a single channel is being transferred, this is it. If
- * multiple parties are being transferred, this is NULL.
- * \param replace_channel If multiple parties are being transferred or the transfer
- * cannot reach across the bridge due to bridge flags, this is
- * the channel connecting their bridge to the destination.
+ * \param transfer_message
*/
void ast_bridge_publish_blind_transfer(struct ast_blind_transfer_message *transfer_message);
@@ -460,7 +453,7 @@
*
* \param bridge_id Uniqueid of the bridge from which to get the snapshot.
* \return Most recent snapshot. ao2_cleanup() when done.
- * \return \c NULL if bridge or snapshot doesn't exist.
+ * \retval NULL if bridge or snapshot doesn't exist.
*/
struct ast_bridge_snapshot *ast_bridge_get_snapshot_by_uniqueid(
const char *bridge_id);
@@ -473,7 +466,7 @@
*
* \param bridge The bridge from which to get the snapshot.
* \return Most recent snapshot. ao2_cleanup() when done.
- * \return \c NULL if there isn't a snapshot.
+ * \retval NULL if there isn't a snapshot.
*/
struct ast_bridge_snapshot *ast_bridge_get_snapshot(
struct ast_bridge *bridge);
@@ -481,8 +474,8 @@
/*!
* \internal
* \brief Initialize the topics for a single bridge.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int bridge_topics_init(struct ast_bridge *bridge);
diff --git a/include/asterisk/stasis_channels.h b/include/asterisk/stasis_channels.h
index 61f1c21..f345228 100644
--- a/include/asterisk/stasis_channels.h
+++ b/include/asterisk/stasis_channels.h
@@ -199,7 +199,7 @@
/*!
* \since 12
* \brief A topic which publishes the events for all channels.
- * \retval Topic for all channel events.
+ * \return Topic for all channel events.
*/
struct stasis_topic *ast_channel_topic_all(void);
@@ -207,7 +207,7 @@
* \since 12
* \brief Secondary channel cache, indexed by name.
*
- * \retval Cache of \ref ast_channel_snapshot.
+ * \return Cache of \ref ast_channel_snapshot.
*/
struct ao2_container *ast_channel_cache_by_name(void);
@@ -215,7 +215,7 @@
* \since 12
* \brief Message type for \ref ast_channel_snapshot_update.
*
- * \retval Message type for \ref ast_channel_snapshot_update.
+ * \return Message type for \ref ast_channel_snapshot_update.
*/
struct stasis_message_type *ast_channel_snapshot_type(void);
@@ -228,7 +228,7 @@
*
* \param chan The channel from which to generate a snapshot
*
- * \retval pointer on success (must be unreffed)
+ * \return pointer on success (must be unreffed)
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_create(
@@ -239,9 +239,9 @@
* \brief Obtain the latest \ref ast_channel_snapshot from the \ref stasis cache. This is
* an ao2 object, so use \ref ao2_cleanup() to deallocate.
*
- * \param unique_id The channel's unique ID
+ * \param uniqueid The channel's unique ID
*
- * \retval A \ref ast_channel_snapshot on success
+ * \return A \ref ast_channel_snapshot on success
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniqueid);
@@ -253,7 +253,7 @@
*
* \param name The channel's name
*
- * \retval A \ref ast_channel_snapshot on success
+ * \return A \ref ast_channel_snapshot on success
* \retval NULL on error
*/
struct ast_channel_snapshot *ast_channel_snapshot_get_latest_by_name(const char *name);
@@ -285,7 +285,7 @@
* \c NULL, ast_json_null() is put into the object.
*
* \return \ref ast_channel_blob message.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct stasis_message *ast_channel_blob_create(struct ast_channel *chan,
struct stasis_message_type *type, struct ast_json *blob);
@@ -301,7 +301,7 @@
* \c NULL, ast_json_null() is put into the object.
*
* \return \ref ast_channel_blob message.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct stasis_message *ast_channel_blob_create_from_cache(
const char *uniqueid, struct stasis_message_type *type,
@@ -317,7 +317,7 @@
* \param blob The JSON blob that defines the data of this \ref ast_multi_channel_blob
*
* \return \ref ast_multi_channel_blob object
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct ast_multi_channel_blob *ast_multi_channel_blob_create(struct ast_json *blob);
@@ -334,7 +334,7 @@
* to retrieve
* \param role The role associated with the channel snapshot
*
- * \retval \ref ast_channel_snapshot matching the role on success
+ * \return \ref ast_channel_snapshot matching the role on success
* \retval NULL on error or not found for the role specified
*/
struct ast_channel_snapshot *ast_multi_channel_blob_get_channel(
@@ -355,7 +355,7 @@
* retrieve
* \param role The role associated with the channel snapshots
*
- * \retval A container containing all \ref ast_channel_snapshot objects matching
+ * \return A container containing all \ref ast_channel_snapshot objects matching
* the role on success.
* \retval NULL on error or not found for the role specified
*/
@@ -369,7 +369,7 @@
*
* \param obj Channel blob object.
* \return Type field value from the blob.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct ast_json *ast_multi_channel_blob_get_json(struct ast_multi_channel_blob *obj);
@@ -399,8 +399,6 @@
* \param blob The blob being published. (NULL if no blob)
*
* \note This will use the current snapshot on the channel and will not generate a new one.
- *
- * \return Nothing
*/
void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_type *type,
struct ast_json *blob);
@@ -416,8 +414,6 @@
* \note As this only accesses the uniqueid and topic of the channel - neither of
* which should ever be changed on a channel anyhow - a channel does not have to
* be locked when calling this function.
- *
- * \return Nothing
*/
void ast_channel_publish_cached_blob(struct ast_channel *chan, struct stasis_message_type *type,
struct ast_json *blob);
@@ -466,7 +462,7 @@
/*!
* \since 12
- * \brief Publish a \ref ast_channel_varset for a channel.
+ * \brief Publish a \ref ast_channel_publish_varset for a channel.
*
* \pre chan is locked
*
@@ -481,7 +477,7 @@
* \since 12
* \brief Message type for when a channel dials another channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_dial_type(void);
@@ -489,7 +485,7 @@
* \since 12
* \brief Message type for when a variable is set on a channel.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_varset_type(void);
@@ -497,7 +493,7 @@
* \since 12
* \brief Message type for when a hangup is requested on a channel.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_hangup_request_type(void);
@@ -505,7 +501,7 @@
* \since 16
* \brief Message type for when a channel is being masqueraded
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_masquerade_type(void);
@@ -513,7 +509,7 @@
* \since 12
* \brief Message type for when DTMF begins on a channel.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_dtmf_begin_type(void);
@@ -521,14 +517,14 @@
* \since 12
* \brief Message type for when DTMF ends on a channel.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_dtmf_end_type(void);
/*!
* \brief Message type for when a hook flash occurs on a channel.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_flash_type(void);
@@ -536,7 +532,7 @@
* \since 12
* \brief Message type for when a channel is placed on hold.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_hold_type(void);
@@ -544,7 +540,7 @@
* \since 12
* \brief Message type for when a channel is removed from hold.
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_unhold_type(void);
@@ -552,7 +548,7 @@
* \since 12
* \brief Message type for when a channel starts spying on another channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_chanspy_start_type(void);
@@ -560,7 +556,7 @@
* \since 12
* \brief Message type for when a channel stops spying on another channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_chanspy_stop_type(void);
@@ -568,7 +564,7 @@
* \since 12
* \brief Message type for a fax operation
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_fax_type(void);
@@ -576,7 +572,7 @@
* \since 12
* \brief Message type for hangup handler related actions
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_hangup_handler_type(void);
@@ -584,7 +580,7 @@
* \since 12
* \brief Message type for starting monitor on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_monitor_start_type(void);
@@ -592,7 +588,7 @@
* \since 12
* \brief Message type for stopping monitor on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_monitor_stop_type(void);
@@ -600,7 +596,7 @@
* \since 18
* \brief Message type for starting mixmonitor on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_start_type(void);
@@ -608,7 +604,7 @@
* \since 18
* \brief Message type for stopping mixmonitor on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_stop_type(void);
@@ -616,7 +612,7 @@
* \since 18
* \brief Message type for muting or unmuting mixmonitor on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_mixmonitor_mute_type(void);
@@ -624,7 +620,7 @@
* \since 18.0.0
* \brief Message type for agent login on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_agent_login_type(void);
@@ -632,7 +628,7 @@
* \since 12.0.0
* \brief Message type for agent logoff on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_agent_logoff_type(void);
@@ -640,7 +636,7 @@
* \since 12
* \brief Message type for starting music on hold on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_moh_start_type(void);
@@ -648,7 +644,7 @@
* \since 12
* \brief Message type for stopping music on hold on a channel
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_moh_stop_type(void);
@@ -656,7 +652,7 @@
* \since 12.4.0
* \brief Message type for a channel starting talking
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_talking_start(void);
@@ -664,7 +660,7 @@
* \since 12.4.0
* \brief Message type for a channel stopping talking
*
- * \retval A stasis message type
+ * \return A stasis message type
*/
struct stasis_message_type *ast_channel_talking_stop(void);
@@ -714,7 +710,7 @@
* \param sanitize The message sanitizer to use on the snapshot
*
* \return JSON object representing channel snapshot.
- * \return \c NULL on error
+ * \retval NULL on error
*/
struct ast_json *ast_channel_snapshot_to_json(const struct ast_channel_snapshot *snapshot,
const struct stasis_message_sanitizer *sanitize);
@@ -726,8 +722,8 @@
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
- * \return True (non-zero) if context, exten or priority are identical.
- * \return False (zero) if context, exten and priority changed.
+ * \retval True (non-zero) if context, exten or priority are identical.
+ * \retval False (zero) if context, exten and priority changed.
*/
int ast_channel_snapshot_cep_equal(
const struct ast_channel_snapshot *old_snapshot,
@@ -740,8 +736,8 @@
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
- * \return True (non-zero) if callerid are identical.
- * \return False (zero) if callerid changed.
+ * \retval True (non-zero) if callerid are identical.
+ * \retval False (zero) if callerid changed.
*/
int ast_channel_snapshot_caller_id_equal(
const struct ast_channel_snapshot *old_snapshot,
@@ -754,8 +750,8 @@
* \param old_snapshot Old snapshot
* \param new_snapshot New snapshot
*
- * \return True (non-zero) if callerid are identical.
- * \return False (zero) if callerid changed.
+ * \retval True (non-zero) if callerid are identical.
+ * \retval False (zero) if callerid changed.
*/
int ast_channel_snapshot_connected_line_equal(
const struct ast_channel_snapshot *old_snapshot,
@@ -763,8 +759,8 @@
/*!
* \brief Initialize the stasis channel topic and message types
- * \return 0 on success
- * \return Non-zero on error
+ * \retval 0 on success
+ * \retval Non-zero on error
*/
int ast_stasis_channels_init(void);
diff --git a/include/asterisk/stasis_internal.h b/include/asterisk/stasis_internal.h
index b3e56f1..2495fc0 100644
--- a/include/asterisk/stasis_internal.h
+++ b/include/asterisk/stasis_internal.h
@@ -56,6 +56,7 @@
* subscriptions without mailboxes will be delivered on the publisher thread.
* \param use_thread_pool Use the thread pool for the subscription. This is only
* relevant if \c needs_mailbox is non-zero.
+ * \param file, lineno, func
* \return New \ref stasis_subscription object.
* \return \c NULL on error.
* \since 12
diff --git a/include/asterisk/stasis_message_router.h b/include/asterisk/stasis_message_router.h
index c186b61..c0821b6 100644
--- a/include/asterisk/stasis_message_router.h
+++ b/include/asterisk/stasis_message_router.h
@@ -51,13 +51,13 @@
* \param topic Topic to subscribe route to.
*
* \return New \ref stasis_message_router.
- * \return \c NULL on error.
+ * \retval NULL on error.
*
* \since 12
*/
+#define stasis_message_router_create(topic) __stasis_message_router_create(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct stasis_message_router *__stasis_message_router_create(
struct stasis_topic *topic, const char *file, int lineno, const char *func);
-#define stasis_message_router_create(topic) __stasis_message_router_create(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Create a new message router object.
@@ -68,13 +68,13 @@
* \param topic Topic to subscribe route to.
*
* \return New \ref stasis_message_router.
- * \return \c NULL on error.
+ * \retval NULL on error.
*
* \since 12.8.0
*/
+#define stasis_message_router_create_pool(topic) __stasis_message_router_create_pool(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
struct stasis_message_router *__stasis_message_router_create_pool(
struct stasis_topic *topic, const char *file, int lineno, const char *func);
-#define stasis_message_router_create_pool(topic) __stasis_message_router_create_pool(topic, __FILE__, __LINE__, __PRETTY_FUNCTION__)
/*!
* \brief Unsubscribe the router from the upstream topic.
@@ -104,9 +104,9 @@
*
* \param router Router.
*
- * \return True (non-zero) if stasis_subscription_final_message() has been
+ * \retval True (non-zero) if stasis_subscription_final_message() has been
* received.
- * \return False (zero) if waiting for the end.
+ * \retval False (zero) if waiting for the end.
*/
int stasis_message_router_is_done(struct stasis_message_router *router);
diff --git a/include/asterisk/stasis_system.h b/include/asterisk/stasis_system.h
index 5595906..81e1403 100644
--- a/include/asterisk/stasis_system.h
+++ b/include/asterisk/stasis_system.h
@@ -37,7 +37,7 @@
* \since 12
* \brief A \ref stasis topic which publishes messages regarding system changes
*
- * \retval \ref stasis_topic for system level changes
+ * \return \ref stasis_topic for system level changes
* \retval NULL on error
*/
struct stasis_topic *ast_system_topic(void);
@@ -47,7 +47,7 @@
* \brief A \ref stasis_message_type for network changes
*
* \retval NULL on error
- * \retval \ref stasis_message_type for network changes
+ * \return \ref stasis_message_type for network changes
*
* \note Messages of this type should always be issued on and expected from
* the \ref ast_system_topic \ref stasis topic
diff --git a/include/asterisk/stasis_test.h b/include/asterisk/stasis_test.h
index d9df1c9..42c169b 100644
--- a/include/asterisk/stasis_test.h
+++ b/include/asterisk/stasis_test.h
@@ -101,6 +101,7 @@
* \param start Index of message to start with.
* \param cmp_cb comparison function. This returns true (non-zero) on match
* and false (zero) on match.
+ * \param data
* \param timeout_millis Number of milliseconds to wait.
* \return Index of the matching message.
* \return Negative for no match.
diff --git a/main/stasis.c b/main/stasis.c
index b825f39..a75fe66 100644
--- a/main/stasis.c
+++ b/main/stasis.c
@@ -250,8 +250,8 @@
* The destructors of both have assertions regarding this to catch ref-counting
* problems where a subscription or topic has had an extra ao2_cleanup().
*
- * The \ref dispatch object is a transient object, which is posted to a
- * subscription's taskprocessor to send a message to the subscriber. They have
+ * The \ref dispatch_exec_sync object is a transient object, which is posted to
+ * a subscription's taskprocessor to send a message to the subscriber. They have
* short life cycles, allocated on one thread, destroyed on another.
*
* During shutdown, or the deletion of a domain object, there are a flurry of
@@ -750,7 +750,6 @@
/*!
* \brief Invoke the subscription's callback.
* \param sub Subscription to invoke.
- * \param topic Topic message was published to.
* \param message Message to send.
*/
static void subscription_invoke(struct stasis_subscription *sub,
diff --git a/main/stasis_bridges.c b/main/stasis_bridges.c
index 9238adc..4a4735a 100644
--- a/main/stasis_bridges.c
+++ b/main/stasis_bridges.c
@@ -752,7 +752,7 @@
* \internal
* \brief Allocate the fields of an \ref ast_bridge_channel_snapshot_pair.
*
- * \param pair A bridge and channel to get snapshots of
+ * \param channel, bridge A bridge and channel to get snapshots of
* \param[out] snapshot_pair An allocated snapshot pair.
* \retval 0 Success
* \retval non-zero Failure
diff --git a/main/stasis_cache.c b/main/stasis_cache.c
index 9c8f8e7..55a3647 100644
--- a/main/stasis_cache.c
+++ b/main/stasis_cache.c
@@ -390,7 +390,7 @@
*
* \note The entries container is already locked.
*
- * \retval Cache-entry on success.
+ * \return Cache-entry on success.
* \retval NULL Not in cache.
*/
static struct stasis_cache_entry *cache_find(struct ao2_container *entries, struct stasis_message_type *type, const char *id)
@@ -625,8 +625,8 @@
*
* \note The returned snapshot has not had its reference bumped.
*
- * \retval Snapshot from the cache.
- * \retval \c NULL if snapshot is not found.
+ * \return Snapshot from the cache.
+ * \retval NULL if snapshot is not found.
*/
static struct stasis_message *cache_entry_by_eid(const struct stasis_cache_entry *entry, const struct ast_eid *eid)
{
diff --git a/main/stasis_state.c b/main/stasis_state.c
index b85462f..75093a0 100644
--- a/main/stasis_state.c
+++ b/main/stasis_state.c
@@ -157,9 +157,10 @@
* \param manager The owning manager
* \param state_topic A state topic to be managed
* \param id The unique id for the state
+ * \param file, line, func
*
* \return A stasis_state object or NULL
- * \return NULL on error
+ * \retval NULL on error
*
* \pre manager->states must be locked.
* \pre manager->states does not contain an object matching key \a id.
@@ -265,9 +266,9 @@
* \param id The unique id for the state (if NULL state_topic is required)
*
* \return The added state object
- * \return NULL on error
+ * \retval NULL on error
*/
-#define state_find_or_add(mgr, top, id) __state_find_or_add(mgr, top, id, __FILE__, __LINE__, __PRETTY_FUNCTION__)
+#define state_find_or_add(manager, state_topic, id) __state_find_or_add(manager, state_topic, id, __FILE__, __LINE__, __PRETTY_FUNCTION__)
static struct stasis_state *__state_find_or_add(struct stasis_state_manager *manager,
struct stasis_topic *state_topic, const char *id,
const char *file, int line, const char *func)
diff --git a/res/res_stasis_snoop.c b/res/res_stasis_snoop.c
index 7e87611..190ee06 100644
--- a/res/res_stasis_snoop.c
+++ b/res/res_stasis_snoop.c
@@ -107,7 +107,7 @@
/*! \internal
* \brief Publish the chanspy message over Stasis-Core
* \param snoop The snoop structure
- * \start start If non-zero, the spying is starting. Otherwise, the spyer is
+ * \param start If non-zero, the spying is starting. Otherwise, the spyer is
* finishing
*/
static void publish_chanspy_message(struct stasis_app_snoop *snoop, int start)
diff --git a/res/stasis/app.c b/res/stasis/app.c
index ee2fd0b..3709033 100644
--- a/res/stasis/app.c
+++ b/res/stasis/app.c
@@ -1030,11 +1030,6 @@
return app->topic;
}
-/*!
- * \brief Send a message to the given application.
- * \param app App to send the message to.
- * \param message Message to send.
- */
void app_send(struct stasis_app *app, struct ast_json *message)
{
stasis_app_cb handler;
diff --git a/res/stasis/app.h b/res/stasis/app.h
index ac4ac59..a59f1dc 100644
--- a/res/stasis/app.h
+++ b/res/stasis/app.h
@@ -55,8 +55,9 @@
* \param name Name of the application.
* \param handler Callback for messages sent to the application.
* \param data Data pointer provided to the callback.
+ * \param subscription_model
* \return New \c res_stasis application.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app *app_create(const char *name, stasis_app_cb handler, void *data, enum stasis_app_subscription_model subscription_model);
@@ -83,8 +84,8 @@
* \brief Checks whether an app is active.
*
* \param app Application to check.
- * \return True (non-zero) if app is active.
- * \return False (zero) if app has been deactivated.
+ * \retval True (non-zero) if app is active.
+ * \retval False (zero) if app has been deactivated.
*/
int app_is_active(struct stasis_app *app);
@@ -92,8 +93,8 @@
* \brief Checks whether a deactivated app has no channels.
*
* \param app Application to check.
- * \param True (non-zero) if app is deactivated, and has no associated channels.
- * \param False (zero) otherwise.
+ * \retval True (non-zero) if app is deactivated, and has no associated channels.
+ * \retval False (zero) otherwise.
*/
int app_is_finished(struct stasis_app *app);
@@ -111,7 +112,7 @@
/*!
* \brief Send a message to an application.
*
- * \param app Application.
+ * \param app App to send the message to.
* \param message Message to send.
*/
void app_send(struct stasis_app *app, struct ast_json *message);
@@ -123,8 +124,8 @@
*
* \param app The application
*
- * \return \c JSON blob on success
- * \return \c NULL on error
+ * \return JSON blob on success
+ * \retval NULL on error
*/
struct ast_json *app_to_json(const struct stasis_app *app);
@@ -133,8 +134,8 @@
*
* \param app Application.
* \param chan Channel to subscribe to.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_subscribe_channel(struct stasis_app *app, struct ast_channel *chan);
@@ -143,8 +144,8 @@
*
* \param app Subscribing application.
* \param chan Channel to unsubscribe from.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_unsubscribe_channel(struct stasis_app *app, struct ast_channel *chan);
@@ -153,8 +154,8 @@
*
* \param app Subscribing application.
* \param channel_id Id of channel to unsubscribe from.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_unsubscribe_channel_id(struct stasis_app *app, const char *channel_id);
@@ -163,8 +164,8 @@
*
* \param app Subscribing application.
* \param channel_id Id of channel to check.
- * \return True (non-zero) if channel is subscribed to \a app.
- * \return False (zero) if channel is not subscribed.
+ * \retval True (non-zero) if channel is subscribed to \a app.
+ * \retval False (zero) if channel is not subscribed.
*/
int app_is_subscribed_channel_id(struct stasis_app *app, const char *channel_id);
@@ -173,18 +174,18 @@
*
* \param app Application.
* \param bridge Bridge to subscribe to.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_subscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
/*!
* \brief Cancel the bridge subscription for an application.
*
- * \param forwards Return from app_subscribe_channel().
+ * \param app Subscribing application.
* \param bridge Bridge to subscribe to.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_unsubscribe_bridge(struct stasis_app *app, struct ast_bridge *bridge);
@@ -193,8 +194,8 @@
*
* \param app Subscribing application.
* \param bridge_id Id of bridge to unsubscribe from.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_unsubscribe_bridge_id(struct stasis_app *app, const char *bridge_id);
@@ -203,8 +204,8 @@
*
* \param app Subscribing application.
* \param bridge_id Id of bridge to check.
- * \return True (non-zero) if bridge is subscribed to \a app.
- * \return False (zero) if bridge is not subscribed.
+ * \retval True (non-zero) if bridge is subscribed to \a app.
+ * \retval False (zero) if bridge is not subscribed.
*/
int app_is_subscribed_bridge_id(struct stasis_app *app, const char *bridge_id);
@@ -212,9 +213,9 @@
* \brief Subscribes an application to a endpoint.
*
* \param app Application.
- * \param chan Endpoint to subscribe to.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \param endpoint Endpoint to subscribe to.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_subscribe_endpoint(struct stasis_app *app, struct ast_endpoint *endpoint);
@@ -223,8 +224,8 @@
*
* \param app Subscribing application.
* \param endpoint_id Id of endpoint to unsubscribe from.
- * \return 0 on success.
- * \return Non-zero on error.
+ * \retval 0 on success.
+ * \retval Non-zero on error.
*/
int app_unsubscribe_endpoint_id(struct stasis_app *app, const char *endpoint_id);
@@ -233,15 +234,15 @@
*
* \param app Subscribing application.
* \param endpoint_id Id of endpoint to check.
- * \return True (non-zero) if endpoint is subscribed to \a app.
- * \return False (zero) if endpoint is not subscribed.
+ * \retval True (non-zero) if endpoint is subscribed to \a app.
+ * \retval False (zero) if endpoint is not subscribed.
*/
int app_is_subscribed_endpoint_id(struct stasis_app *app, const char *endpoint_id);
/*!
* \brief Set the snapshot of the channel that this channel will replace
*
- * \param channel The channel on which this will be set
+ * \param chan The channel on which this will be set
* \param replace_snapshot The snapshot of the channel that is being replaced
*
* \retval zero success
@@ -252,7 +253,7 @@
/*!
* \brief Set the app that the replacement channel will be controlled by
*
- * \param channel The channel on which this will be set
+ * \param chan The channel on which this will be set
* \param replace_app The app that will be controlling this channel
*
* \retval zero success
@@ -263,7 +264,7 @@
/*!
* \brief Get the app that the replacement channel will be controlled by
*
- * \param channel The channel on which this will be set
+ * \param chan The channel on which this will be set
*
* \retval NULL on error
* \return the name of the controlling app (must be ast_free()d)
diff --git a/res/stasis/control.h b/res/stasis/control.h
index 67aa3b7..137ac81 100644
--- a/res/stasis/control.h
+++ b/res/stasis/control.h
@@ -36,7 +36,7 @@
* \param app stasis_app for which this control is being created.
*
* \return New control object.
- * \return \c NULL on error.
+ * \retval NULL on error.
*/
struct stasis_app_control *control_create(struct ast_channel *channel, struct stasis_app *app);
@@ -45,8 +45,6 @@
* \since 13.9.0
*
* \param control Control object to flush command queue.
- *
- * \return Nothing
*/
void control_flush_queue(struct stasis_app_control *control);
@@ -72,7 +70,7 @@
*
* \param control Control to count commands on
*
- * \retval number of commands in the command que
+ * \return number of commands in the command que
*/
int control_command_count(struct stasis_app_control *control);
@@ -80,8 +78,8 @@
* \brief Returns true if control_continue() has been called on this \a control.
*
* \param control Control to query.
- * \return True (non-zero) if control_continue() has been called.
- * \return False (zero) otherwise.
+ * \retval True (non-zero) if control_continue() has been called.
+ * \retval False (zero) otherwise.
*/
int control_is_done(struct stasis_app_control *control);
@@ -91,7 +89,7 @@
* \brief Dispatch all queued prestart commands
*
* \param control The control for chan
- * \param channel The channel on which commands should be executed
+ * \param chan The channel on which commands should be executed
*
* \return The number of commands executed
*/
@@ -103,7 +101,7 @@
*
* \param control Control to query.
*
- * \returns A pointer to the associated stasis_app
+ * \return A pointer to the associated stasis_app
*/
struct stasis_app *control_app(struct stasis_app_control *control);
diff --git a/res/stasis/messaging.h b/res/stasis/messaging.h
index 75ef5c9..aa3d6cc 100644
--- a/res/stasis/messaging.h
+++ b/res/stasis/messaging.h
@@ -45,9 +45,6 @@
*
* \param app_name Name of the stasis application to unsubscribe from messaging
* \param endpoint_id The ID of the endpoint we no longer care about
- *
- * \retval 0 success
- * \retval -1 error
*/
void messaging_app_unsubscribe_endpoint(const char *app_name, const char *endpoint_id);
@@ -56,7 +53,7 @@
*
* \param app_name The name of the \ref stasis application to subscribe to \c endpoint
* \param endpoint The endpoint object to subscribe to
- * \param message_received_cb The callback to call when a message is received
+ * \param callback The callback to call when a message is received
* \param pvt An ao2 ref counted object that will be passed to the callback.
*
* \retval 0 subscription was successful
diff --git a/res/stasis/stasis_bridge.c b/res/stasis/stasis_bridge.c
index fdfd8fb..d5ab00a 100644
--- a/res/stasis/stasis_bridge.c
+++ b/res/stasis/stasis_bridge.c
@@ -278,8 +278,6 @@
* \param bridge_channel Bridge channel to pull.
*
* \note On entry, self is already locked.
- *
- * \return Nothing
*/
static void bridge_stasis_pull(struct ast_bridge *self, struct ast_bridge_channel *bridge_channel)
{
diff --git a/res/stasis/stasis_bridge.h b/res/stasis/stasis_bridge.h
index 6e2a48b..531da92 100644
--- a/res/stasis/stasis_bridge.h
+++ b/res/stasis/stasis_bridge.h
@@ -61,8 +61,6 @@
* \internal
* \brief Initialize the Stasis bridge subclass.
* \since 12.5.0
- *
- * \return Nothing
*/
void bridge_stasis_init(void);
diff --git a/res/stasis_recording/stored.c b/res/stasis_recording/stored.c
index 3232c6d..7fe2b7c 100644
--- a/res/stasis_recording/stored.c
+++ b/res/stasis_recording/stored.c
@@ -85,7 +85,7 @@
*
* \param path Path to split.
* \param[out] dir Output parameter for directory portion.
- * \param[out] fail Output parameter for the file portion.
+ * \param[out] file Output parameter for the file portion.
* \return 0 on success.
* \return Non-zero on error.
*/
--
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17490
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 19
Gerrit-Change-Id: Iea50173e785b2e9d49bc24c0af7111cfd96d44a9
Gerrit-Change-Number: 17490
Gerrit-PatchSet: 2
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-Reviewer: George Joseph <gjoseph at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211118/e3ada91a/attachment-0001.html>
More information about the asterisk-code-review
mailing list