Bridge API comment tweaks.

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@379703 65c4cc65-6c06-0410-ace0-fbb531ad65f3

4 files changed, 77 insertions, 37 deletions

diff --git a/bridges/bridge_builtin_features.c b/bridges/bridge_builtin_features.c
index 21af92855..13bf4bb8b 100644
--- a/bridges/bridge_builtin_features.c
+++ b/bridges/bridge_builtin_features.c
@@ -241,7 +241,11 @@ static int feature_attended_transfer(struct ast_bridge *bridge, struct ast_bridg
 /*! \brief Internal built in feature for hangup */
 static int feature_hangup(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, void *hook_pvt)
 {
-	/* This is very simple, we basically change the state on the bridge channel to end and the core takes care of the rest */
+	/*
+	 * This is very simple, we simply change the state on the
+	 * bridge_channel to force the channel out of the bridge and the
+	 * core takes care of the rest.
+	 */
 	ast_bridge_change_state(bridge_channel, AST_BRIDGE_CHANNEL_STATE_END);
 	return 0;
 }
diff --git a/include/asterisk/bridging.h b/include/asterisk/bridging.h
index 2c41f4618..2d0d74b82 100644
--- a/include/asterisk/bridging.h
+++ b/include/asterisk/bridging.h
@@ -251,7 +251,8 @@ struct ast_bridge {
 	AST_LIST_HEAD_NOLOCK(, ast_bridge_channel) channels;
 	};
 
-/*! \brief Create a new bridge
+/*!
+ * \brief Create a new bridge
  *
  * \param capabilities The capabilities that we require to be used on the bridge
  * \param flags Flags that will alter the behavior of the bridge
@@ -297,7 +298,8 @@ static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *fil
 	__ao2_unlock(bridge, file, function, line, var);
 }
 
-/*! \brief See if it is possible to create a bridge
+/*!
+ * \brief See if it is possible to create a bridge
  *
  * \param capabilities The capabilities that the bridge will use
  *
@@ -315,7 +317,8 @@ static inline void _ast_bridge_unlock(struct ast_bridge *bridge, const char *fil
  */
 int ast_bridge_check(uint32_t capabilities);
 
-/*! \brief Destroy a bridge
+/*!
+ * \brief Destroy a bridge
  *
  * \param bridge Bridge to destroy
  *
@@ -332,7 +335,8 @@ int ast_bridge_check(uint32_t capabilities);
  */
 int ast_bridge_destroy(struct ast_bridge *bridge);
 
-/*! \brief Join (blocking) a channel to a bridge
+/*!
+ * \brief Join (blocking) a channel to a bridge
  *
  * \param bridge Bridge to join
  * \param chan Channel to join
@@ -365,7 +369,8 @@ enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
 	struct ast_bridge_features *features,
 	struct ast_bridge_tech_optimizations *tech_args);
 
-/*! \brief Impart (non-blocking) a channel on a bridge
+/*!
+ * \brief Impart (non-blocking) a channel onto a bridge
  *
  * \param bridge Bridge to impart on
  * \param chan Channel to impart
@@ -395,7 +400,8 @@ enum ast_bridge_channel_state ast_bridge_join(struct ast_bridge *bridge,
  */
 int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap, struct ast_bridge_features *features, int allow_hangup);
 
-/*! \brief Depart a channel from a bridge
+/*!
+ * \brief Depart a channel from a bridge
  *
  * \param bridge Bridge to depart from
  * \param chan Channel to depart
@@ -418,7 +424,8 @@ int ast_bridge_impart(struct ast_bridge *bridge, struct ast_channel *chan, struc
  */
 int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
 
-/*! \brief Remove a channel from a bridge
+/*!
+ * \brief Remove a channel from a bridge
  *
  * \param bridge Bridge that the channel is to be removed from
  * \param chan Channel to remove
@@ -441,7 +448,8 @@ int ast_bridge_depart(struct ast_bridge *bridge, struct ast_channel *chan);
  */
 int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
 
-/*! \brief Merge two bridges together
+/*!
+ * \brief Merge two bridges together
  *
  * \param bridge0 First bridge
  * \param bridge1 Second bridge
@@ -463,7 +471,8 @@ int ast_bridge_remove(struct ast_bridge *bridge, struct ast_channel *chan);
  */
 int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
 
-/*! \brief Suspend a channel temporarily from a bridge
+/*!
+ * \brief Suspend a channel temporarily from a bridge
  *
  * \param bridge Bridge to suspend the channel from
  * \param chan Channel to suspend
@@ -486,7 +495,8 @@ int ast_bridge_merge(struct ast_bridge *bridge0, struct ast_bridge *bridge1);
  */
 int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
 
-/*! \brief Unsuspend a channel from a bridge
+/*!
+ * \brief Unsuspend a channel from a bridge
  *
  * \param bridge Bridge to unsuspend the channel from
  * \param chan Channel to unsuspend
@@ -508,7 +518,8 @@ int ast_bridge_suspend(struct ast_bridge *bridge, struct ast_channel *chan);
  */
 int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
 
-/*! \brief Change the state of a bridged channel
+/*!
+ * \brief Change the state of a bridged channel
  *
  * \param bridge_channel Channel to change the state on
  * \param new_state The new state to place the channel into
@@ -527,8 +538,9 @@ int ast_bridge_unsuspend(struct ast_bridge *bridge, struct ast_channel *chan);
  */
 void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast_bridge_channel_state new_state);
 
-/*! \brief Adjust the internal mixing sample rate of a bridge used during
- *         multimix mode.
+/*!
+ * \brief Adjust the internal mixing sample rate of a bridge
+ * used during multimix mode.
  *
  * \param bridge Channel to change the sample rate on.
  * \param sample_rate the sample rate to change to. If a
@@ -538,8 +550,9 @@ void ast_bridge_change_state(struct ast_bridge_channel *bridge_channel, enum ast
  */
 void ast_bridge_set_internal_sample_rate(struct ast_bridge *bridge, unsigned int sample_rate);
 
-/*! \brief Adjust the internal mixing interval of a bridge used during
- *         multimix mode.
+/*!
+ * \brief Adjust the internal mixing interval of a bridge used
+ * during multimix mode.
  *
  * \param bridge Channel to change the sample rate on.
  * \param mixing_interval the sample rate to change to.  If 0 is set
diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h
index 2984684d4..a9e587505 100644
--- a/include/asterisk/bridging_features.h
+++ b/include/asterisk/bridging_features.h
@@ -36,13 +36,21 @@ enum ast_bridge_feature_flags {
 	AST_BRIDGE_FLAG_SMART = (1 << 1),
 };
 
-/*! \brief Built in features */
+/*! \brief Built in DTMF features */
 enum ast_bridge_builtin_feature {
-	/*! DTMF Based Blind Transfer */
-	AST_BRIDGE_BUILTIN_BLINDTRANSFER = 0,
-	/*! DTMF Based Attended Transfer */
+	/*! DTMF based Blind Transfer */
+	AST_BRIDGE_BUILTIN_BLINDTRANSFER,
+	/*! DTMF based Attended Transfer */
 	AST_BRIDGE_BUILTIN_ATTENDEDTRANSFER,
-	/*! DTMF Based Hangup Feature */
+	/*!
+	 * DTMF based depart bridge feature
+	 *
+	 * \note Imparted channels are optionally hangup depending upon
+	 * how it was imparted.
+	 *
+	 * \note Joined channels exit the bridge with
+	 * AST_BRIDGE_CHANNEL_STATE_END.
+	 */
 	AST_BRIDGE_BUILTIN_HANGUP,
 
 	/*! End terminator for list of built in features. Must remain last. */
@@ -124,7 +132,7 @@ struct ast_bridge_features {
 	void *talker_pvt_data;
 	/*! Feature flags that are enabled */
 	struct ast_flags feature_flags;
-	/*! Bit to indicate that the hook list is useful and should be considered when looking for DTMF features */
+	/*! Bit to indicate that the feature_flags and hook list is setup */
 	unsigned int usable:1;
 	/*! Bit to indicate whether the channel/bridge is muted or not */
 	unsigned int mute:1;
@@ -155,7 +163,8 @@ struct ast_bridge_features_attended_transfer {
 	char context[AST_MAX_CONTEXT];
 };
 
-/*! \brief Register a handler for a built in feature
+/*!
+ * \brief Register a handler for a built in feature
  *
  * \param feature The feature that the handler will be responsible for
  * \param callback The callback function that will handle it
@@ -175,7 +184,8 @@ struct ast_bridge_features_attended_transfer {
  */
 int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_bridge_features_hook_callback callback, const char *dtmf);
 
-/*! \brief Unregister a handler for a built in feature
+/*!
+ * \brief Unregister a handler for a built in feature
  *
  * \param feature The feature to unregister
  *
@@ -192,7 +202,8 @@ int ast_bridge_features_register(enum ast_bridge_builtin_feature feature, ast_br
  */
 int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
 
-/*! \brief Attach a custom hook to a bridge features structure
+/*!
+ * \brief Attach a custom hook to a bridge features structure
  *
  * \param features Bridge features structure
  * \param dtmf DTMF string to be activated upon
@@ -224,7 +235,8 @@ int ast_bridge_features_hook(struct ast_bridge_features *features,
 	void *hook_pvt,
 	ast_bridge_features_hook_pvt_destructor destructor);
 
-/*! \brief Set a callback on the features structure to receive talking notifications on.
+/*!
+ * \brief Set a callback on the features structure to receive talking notifications on.
  *
  * \param features Bridge features structure
  * \param talker_cb Callback function to execute when talking events occur in the bridge core.
@@ -239,7 +251,8 @@ int ast_bridge_features_set_talk_detector(struct ast_bridge_features *features,
 	ast_bridge_talking_indicate_destructor talker_destructor,
 	void *pvt_data);
 
-/*! \brief Enable a built in feature on a bridge features structure
+/*!
+ * \brief Enable a built in feature on a bridge features structure
  *
  * \param features Bridge features structure
  * \param feature Feature to enable
@@ -263,7 +276,8 @@ int ast_bridge_features_set_talk_detector(struct ast_bridge_features *features,
  */
 int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_bridge_builtin_feature feature, const char *dtmf, void *config);
 
-/*! \brief Set a flag on a bridge features structure
+/*!
+ * \brief Set a flag on a bridge features structure
  *
  * \param features Bridge features structure
  * \param flag Flag to enable
@@ -284,7 +298,8 @@ int ast_bridge_features_enable(struct ast_bridge_features *features, enum ast_br
  */
 int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_bridge_feature_flags flag);
 
-/*! \brief Initialize bridge features structure
+/*!
+ * \brief Initialize bridge features structure
  *
  * \param features Bridge featues structure
  *
@@ -305,7 +320,8 @@ int ast_bridge_features_set_flag(struct ast_bridge_features *features, enum ast_
  */
 int ast_bridge_features_init(struct ast_bridge_features *features);
 
-/*! \brief Clean up the contents of a bridge features structure
+/*!
+ * \brief Clean up the contents of a bridge features structure
  *
  * \param features Bridge features structure
  *
@@ -327,7 +343,8 @@ int ast_bridge_features_init(struct ast_bridge_features *features);
  */
 int ast_bridge_features_cleanup(struct ast_bridge_features *features);
 
-/*! \brief Play a DTMF stream into a bridge, optionally not to a given channel
+/*!
+ * \brief Play a DTMF stream into a bridge, optionally not to a given channel
  *
  * \param bridge Bridge to play stream into
  * \param dtmf DTMF to play
diff --git a/include/asterisk/bridging_technology.h b/include/asterisk/bridging_technology.h
index ccc87fb63..d09c4bec4 100644
--- a/include/asterisk/bridging_technology.h
+++ b/include/asterisk/bridging_technology.h
@@ -81,7 +81,8 @@ struct ast_bridge_technology {
 	AST_RWLIST_ENTRY(ast_bridge_technology) entry;
 };
 
-/*! \brief Register a bridge technology for use
+/*!
+ * \brief Register a bridge technology for use
  *
  * \param technology The bridge technology to register
  * \param mod The module that is registering the bridge technology
@@ -104,7 +105,8 @@ int __ast_bridge_technology_register(struct ast_bridge_technology *technology, s
 /*! \brief See \ref __ast_bridge_technology_register() */
 #define ast_bridge_technology_register(technology) __ast_bridge_technology_register(technology, ast_module_info->self)
 
-/*! \brief Unregister a bridge technology from use
+/*!
+ * \brief Unregister a bridge technology from use
  *
  * \param technology The bridge technology to unregister
  *
@@ -123,7 +125,8 @@ int __ast_bridge_technology_register(struct ast_bridge_technology *technology, s
  */
 int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
 
-/*! \brief Feed notification that a frame is waiting on a channel into the bridging core
+/*!
+ * \brief Feed notification that a frame is waiting on a channel into the bridging core
  *
  * \param bridge The bridge that the notification should influence
  * \param bridge_channel Bridge channel the notification was received on (if known)
@@ -143,7 +146,8 @@ int ast_bridge_technology_unregister(struct ast_bridge_technology *technology);
  */
 void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, struct ast_channel *chan, int outfd);
 
-/*! \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
+/*!
+ * \brief Lets the bridging indicate when a bridge channel has stopped or started talking.
  *
  * \note All DSP functionality on the bridge has been pushed down to the lowest possible
  * layer, which in this case is the specific bridging technology being used. Since it
@@ -158,7 +162,8 @@ void ast_bridge_handle_trip(struct ast_bridge *bridge, struct ast_bridge_channel
  */
 void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_channel *bridge_channel, int started_talking);
 
-/*! \brief Suspend a bridge technology from consideration
+/*!
+ * \brief Suspend a bridge technology from consideration
  *
  * \param technology The bridge technology to suspend
  *
@@ -174,7 +179,8 @@ void ast_bridge_notify_talking(struct ast_bridge *bridge, struct ast_bridge_chan
  */
 void ast_bridge_technology_suspend(struct ast_bridge_technology *technology);
 
-/*! \brief Unsuspend a bridge technology
+/*!
+ * \brief Unsuspend a bridge technology
  *
  * \param technology The bridge technology to unsuspend
  *