[Asterisk-code-review] pbx: Update doxygen for extension state watchers. (asterisk[master])

[Joshua Colp]

Joshua Colp has submitted this change and it was merged.

Change subject: pbx: Update doxygen for extension state watchers.
......................................................................


pbx: Update doxygen for extension state watchers.

Change-Id: Id1403b12136de62a272c01bb355aef65fd2c2d1e
---
M include/asterisk/pbx.h
M main/pbx.c
2 files changed, 30 insertions(+), 21 deletions(-)

Approvals:
  Kevin Harwell: Looks good to me, but someone else must approve
  Joshua Colp: Looks good to me, approved; Verified



diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 3b3b841..18b5760 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -582,70 +582,80 @@
 const char *ast_extension_state2str(int extension_state);
 
 /*!
- * \brief Registers a state change callback with destructor.
+ * \brief Add watcher for extension states with destructor.
  * \since 1.8.9
  * \since 10.1.0
  *
  * \param context which context to look in
  * \param exten which extension to get state
  * \param change_cb callback to call if state changed
- * \param destroy_cb callback to call when registration destroyed.
- * \param data to pass to callback
+ * \param destroy_cb callback to call when the watcher is destroyed.
+ * \param data to pass to callbacks
+ *
+ * \note If context and exten are NULL then the added watcher is global.
+ * The change_cb is called for every extension's state change.
  *
  * \note The change_cb is called if the state of an extension is changed.
  *
- * \note The destroy_cb is called when the registration is
- * deleted so the registerer can release any associated
- * resources.
+ * \note The destroy_cb is called when the watcher is deleted so the
+ * watcher can release any associated resources.
  *
  * \retval -1 on failure
+ * \retval 0 Global watcher added successfully
  * \retval ID on success
  */
 int ast_extension_state_add_destroy(const char *context, const char *exten,
 	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
 
 /*!
- * \brief Registers an extended state change callback with destructor.
+ * \brief Add watcher for extended extension states with destructor.
  * \since 11
  *
  * \param context which context to look in
  * \param exten which extension to get state
  * \param change_cb callback to call if state changed
- * \param destroy_cb callback to call when registration destroyed.
- * \param data to pass to callback
+ * \param destroy_cb callback to call when the watcher is destroyed.
+ * \param data to pass to callbacks
+ *
+ * \note If context and exten are NULL then the added watcher is global.
+ * The change_cb is called for every extension's state change.
  *
  * \note The change_cb is called if the state of an extension is changed.
  * The extended state is passed to the callback in the device_state_info
  * member of ast_state_cb_info.
  *
- * \note The destroy_cb is called when the registration is
- * deleted so the registerer can release any associated
- * resources.
+ * \note The destroy_cb is called when the watcher is deleted so the
+ * watcher can release any associated resources.
  *
  * \retval -1 on failure
+ * \retval 0 Global watcher added successfully
  * \retval ID on success
  */
 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
 	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data);
 
 /*!
- * \brief Registers a state change callback
+ * \brief Add watcher for extension states.
  *
  * \param context which context to look in
  * \param exten which extension to get state
  * \param change_cb callback to call if state changed
  * \param data to pass to callback
  *
+ * \note If context and exten are NULL then the added watcher is global.
+ * The change_cb is called for every extension's state change.
+ *
  * \note The change_cb is called if the state of an extension is changed.
  *
  * \retval -1 on failure
+ * \retval 0 Global watcher added successfully
  * \retval ID on success
  */
 int ast_extension_state_add(const char *context, const char *exten,
 	ast_state_cb_type change_cb, void *data);
 
 /*!
- * \brief Registers an extended state change callback
+ * \brief Add watcher for extended extension states.
  * \since 11
  *
  * \param context which context to look in
@@ -653,20 +663,24 @@
  * \param change_cb callback to call if state changed
  * \param data to pass to callback
  *
+ * \note If context and exten are NULL then the added watcher is global.
+ * The change_cb is called for every extension's state change.
+ *
  * \note The change_cb is called if the state of an extension is changed.
  * The extended state is passed to the callback in the device_state_info
  * member of ast_state_cb_info.
  *
  * \retval -1 on failure
+ * \retval 0 Global watcher added successfully
  * \retval ID on success
  */
 int ast_extension_state_add_extended(const char *context, const char *exten,
 	ast_state_cb_type change_cb, void *data);
 
 /*!
- * \brief Deletes a registered state change callback by ID
+ * \brief Deletes a state change watcher by ID
  *
- * \param id of the registered state callback to delete
+ * \param id of the state watcher to delete (0 for global watcher)
  * \param change_cb callback to call if state changed (Used if id == 0 (global))
  *
  * \retval 0 success
diff --git a/main/pbx.c b/main/pbx.c
index 7efbdee..1b78bbb 100644
--- a/main/pbx.c
+++ b/main/pbx.c
@@ -3732,28 +3732,24 @@
 	return id;
 }
 
-/*! \brief Add watcher for extension states with destructor */
 int ast_extension_state_add_destroy(const char *context, const char *exten,
 	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data)
 {
 	return extension_state_add_destroy(context, exten, change_cb, destroy_cb, data, 0);
 }
 
-/*! \brief Add watcher for extension states */
 int ast_extension_state_add(const char *context, const char *exten,
 	ast_state_cb_type change_cb, void *data)
 {
 	return extension_state_add_destroy(context, exten, change_cb, NULL, data, 0);
 }
 
-/*! \brief Add watcher for extended extension states with destructor */
 int ast_extension_state_add_destroy_extended(const char *context, const char *exten,
 	ast_state_cb_type change_cb, ast_state_cb_destroy_type destroy_cb, void *data)
 {
 	return extension_state_add_destroy(context, exten, change_cb, destroy_cb, data, 1);
 }
 
-/*! \brief Add watcher for extended extension states */
 int ast_extension_state_add_extended(const char *context, const char *exten,
 	ast_state_cb_type change_cb, void *data)
 {
@@ -3775,7 +3771,6 @@
 	return 0;
 }
 
-/*! \brief  ast_extension_state_del: Remove a watcher from the callback list */
 int ast_extension_state_del(int id, ast_state_cb_type change_cb)
 {
 	struct ast_state_cb *p_cur;

-- 
To view, visit https://gerrit.asterisk.org/2554
To unsubscribe, visit https://gerrit.asterisk.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: Id1403b12136de62a272c01bb355aef65fd2c2d1e
Gerrit-PatchSet: 1
Gerrit-Project: asterisk
Gerrit-Branch: master
Gerrit-Owner: Richard Mudgett <rmudgett at digium.com>
Gerrit-Reviewer: Anonymous Coward #1000019
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>