[asterisk-commits] rmudgett: trunk r396857 - in /trunk: apps/ channels/ main/ res/ res/parking/ ...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Fri Aug 16 12:33:26 CDT 2013
Author: rmudgett
Date: Fri Aug 16 12:33:21 2013
New Revision: 396857
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=396857
Log:
Doxygen comment tweaks.
Modified:
trunk/apps/app_queue.c
trunk/channels/chan_sip.c
trunk/main/bridge_channel.c
trunk/main/cdr.c
trunk/main/data.c
trunk/main/db.c
trunk/main/features.c
trunk/main/file.c
trunk/main/format.c
trunk/main/indications.c
trunk/main/manager.c
trunk/main/message.c
trunk/main/pbx.c
trunk/main/pickup.c
trunk/main/rtp_engine.c
trunk/main/stasis_channels.c
trunk/main/xmldoc.c
trunk/res/parking/parking_bridge_features.c
trunk/res/res_rtp_asterisk.c
trunk/tests/test_abstract_jb.c
trunk/tests/test_cdr.c
trunk/tests/test_cel.c
trunk/tests/test_jitterbuf.c
trunk/tests/test_voicemail_api.c
Modified: trunk/apps/app_queue.c
URL: http://svnview.digium.com/svn/asterisk/trunk/apps/app_queue.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/apps/app_queue.c (original)
+++ trunk/apps/app_queue.c Fri Aug 16 12:33:21 2013
@@ -2060,7 +2060,8 @@
}
/*!
- * \internal \brief Determine if a queue member is available
+ * \internal
+ * \brief Determine if a queue member is available
* \retval 1 if the member is available
* \retval 0 if the member is not available
*/
Modified: trunk/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/trunk/channels/chan_sip.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/channels/chan_sip.c (original)
+++ trunk/channels/chan_sip.c Fri Aug 16 12:33:21 2013
@@ -7724,7 +7724,10 @@
return res;
}
-/*! \internal \brief Create and initialize UDPTL for the specified dialog
+/*!
+ * \internal
+ * \brief Create and initialize UDPTL for the specified dialog
+ *
* \param p SIP private structure to create UDPTL object for
* \pre p is locked
* \pre p->owner is locked
@@ -14443,7 +14446,10 @@
return 0;
}
-/*! \internal \brief Find the channel that is causing the RINGING update, ref'd */
+/*!
+ * \internal
+ * \brief Find the channel that is causing the RINGING update, ref'd
+ */
static struct ast_channel *find_ringing_channel(struct ao2_container *device_state_info, struct sip_pvt *p)
{
struct ao2_iterator citer;
@@ -16386,7 +16392,10 @@
}
}
-/*! \internal \brief Create a new route
+/*!
+ * \internal
+ * \brief Create a new route
+ *
* \retval NULL on error
* \retval sip_route on success
*/
@@ -16415,7 +16424,10 @@
return route;
}
-/*! \internal \brief copy route-set
+/*!
+ * \internal
+ * \brief copy route-set
+ *
* \retval non-zero on failure
* \retval 0 on success
*/
@@ -17045,7 +17057,9 @@
ast_sockaddr_split_hostport(*hostport, hostport, &dont_care, PARSE_PORT_IGNORE);
}
-/*! \internal \brief Helper function to update a peer's lastmsgssent value
+/*!
+ * \internal
+ * \brief Helper function to update a peer's lastmsgssent value
*/
static void update_peer_lastmsgssent(struct sip_peer *peer, int value, int locked)
{
@@ -17059,13 +17073,16 @@
}
-/*! \brief Verify registration of user
- - Registration is done in several steps, first a REGISTER without auth
- to get a challenge (nonce) then a second one with auth
- - Registration requests are only matched with peers that are marked as "dynamic"
+/*!
+ * \brief Verify registration of user
+ *
+ * \details
+ * - Registration is done in several steps, first a REGISTER without auth
+ * to get a challenge (nonce) then a second one with auth
+ * - Registration requests are only matched with peers that are marked as "dynamic"
*/
static enum check_auth_result register_verify(struct sip_pvt *p, struct ast_sockaddr *addr,
- struct sip_request *req, const char *uri)
+ struct sip_request *req, const char *uri)
{
enum check_auth_result res = AUTH_NOT_FOUND;
struct sip_peer *peer;
@@ -27207,7 +27224,10 @@
return handler_result;
}
-/*! \internal \brief Subscribe to MWI events for the specified peer
+/*!
+ * \internal
+ * \brief Subscribe to MWI events for the specified peer
+ *
* \note The peer cannot be locked during this method. sip_send_mwi_peer will
* attempt to lock the peer after the event subscription lock is held; if the peer is locked during
* this method then we will attempt to lock the event subscription lock but after the peer, creating
Modified: trunk/main/bridge_channel.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/bridge_channel.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/bridge_channel.c (original)
+++ trunk/main/bridge_channel.c Fri Aug 16 12:33:21 2013
@@ -108,7 +108,10 @@
ast_bridge_channel_unlock(bridge_channel);
}
-/*! \internal \brief Poke the bridge_channel thread */
+/*!
+ * \internal
+ * \brief Poke the bridge_channel thread
+ */
static void bridge_channel_poke(struct ast_bridge_channel *bridge_channel)
{
if (!pthread_equal(pthread_self(), bridge_channel->thread)) {
@@ -487,7 +490,10 @@
return ast_bridge_channel_write_control_data(bridge_channel, AST_CONTROL_UNHOLD, NULL, 0);
}
-/*! \internal \brief Helper function to kick off a PBX app on a bridge_channel */
+/*!
+ * \internal
+ * \brief Helper function to kick off a PBX app on a bridge_channel
+ */
static int run_app_helper(struct ast_channel *chan, const char *app_name, const char *app_args)
{
int res = 0;
@@ -983,7 +989,10 @@
}
}
-/*! \internal \brief Write a DTMF stream out to a channel */
+/*!
+ * \internal
+ * \brief Write a DTMF stream out to a channel
+ */
static int bridge_channel_write_dtmf_stream(struct ast_bridge_channel *bridge_channel, const char *dtmf)
{
return bridge_channel_write_action_data(bridge_channel,
@@ -1099,7 +1108,10 @@
}
}
-/*! \internal \brief Indicate that a bridge_channel is talking */
+/*!
+ * \internal
+ * \brief Indicate that a bridge_channel is talking
+ */
static void bridge_channel_talking(struct ast_bridge_channel *bridge_channel, int talking)
{
struct ast_bridge_features *features = bridge_channel->features;
@@ -1140,7 +1152,10 @@
char context[AST_MAX_CONTEXT];
};
-/*! \internal \brief Execute after bridge actions on a channel when it leaves a bridge */
+/*!
+ * \internal
+ * \brief Execute after bridge actions on a channel when it leaves a bridge
+ */
static void after_bridge_move_channel(struct ast_channel *chan_bridged, void *data)
{
RAII_VAR(struct ast_channel *, chan_target, data, ao2_cleanup);
@@ -1177,7 +1192,10 @@
ast_party_connected_line_free(&connected_target);
}
-/*! \internal \brief Execute logic to cleanup when after bridge fails */
+/*!
+ * \internal
+ * \brief Execute logic to cleanup when after bridge fails
+ */
static void after_bridge_move_channel_fail(enum ast_bridge_after_cb_reason reason, void *data)
{
RAII_VAR(struct ast_channel *, chan_target, data, ao2_cleanup);
@@ -1187,7 +1205,10 @@
ast_softhangup(chan_target, AST_SOFTHANGUP_DEV);
}
-/*! \internal \brief Perform a blind transfer on a channel in a bridge */
+/*!
+ * \internal
+ * \brief Perform a blind transfer on a channel in a bridge
+ */
static void bridge_channel_blind_transfer(struct ast_bridge_channel *bridge_channel,
struct blind_transfer_data *blind_data)
{
@@ -1195,7 +1216,10 @@
bridge_channel_handle_hangup(bridge_channel);
}
-/*! \internal \brief Perform an attended transfer on a channel in a bridge */
+/*!
+ * \internal
+ * \brief Perform an attended transfer on a channel in a bridge
+ */
static void bridge_channel_attended_transfer(struct ast_bridge_channel *bridge_channel,
const char *target_chan_name)
{
Modified: trunk/main/cdr.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/cdr.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/cdr.c (original)
+++ trunk/main/cdr.c Fri Aug 16 12:33:21 2013
@@ -1545,7 +1545,10 @@
return 1;
}
-/*! \internal \brief Convert a dial status to a CDR disposition */
+/*!
+ * \internal
+ * \brief Convert a dial status to a CDR disposition
+ */
static enum ast_cdr_disposition dial_status_to_disposition(const char *dial_status)
{
RAII_VAR(struct module_config *, mod_cfg,
@@ -1898,13 +1901,19 @@
return 0;
}
-/*! \internal \brief Filter channel snapshots by technology */
+/*!
+ * \internal
+ * \brief Filter channel snapshots by technology
+ */
static int filter_channel_snapshot(struct ast_channel_snapshot *snapshot)
{
return snapshot->tech_properties & AST_CHAN_TP_INTERNAL;
}
-/*! \internal \brief Filter a channel cache update */
+/*!
+ * \internal
+ * \brief Filter a channel cache update
+ */
static int filter_channel_cache_message(struct ast_channel_snapshot *old_snapshot,
struct ast_channel_snapshot *new_snapshot)
{
@@ -2209,7 +2218,9 @@
}
/*!
- * \internal \brief Build and add bridge candidates based on a CDR
+ * \internal
+ * \brief Build and add bridge candidates based on a CDR
+ *
* \param bridge_id The ID of the bridge we need candidates for
* \param candidates The container of \ref bridge_candidate objects
* \param cdr The \ref cdr_object that is our candidate
@@ -2303,7 +2314,9 @@
}
/*!
- * \internal \brief Create a new CDR, append it to an existing CDR, and update its snapshots
+ * \internal
+ * \brief Create a new CDR, append it to an existing CDR, and update its snapshots
+ *
* \note The new CDR will be automatically transitioned to the bridge state
*/
static void bridge_candidate_add_to_cdr(struct cdr_object *cdr,
Modified: trunk/main/data.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/data.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/data.c (original)
+++ trunk/main/data.c Fri Aug 16 12:33:21 2013
@@ -3302,7 +3302,10 @@
#endif
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void data_shutdown(void)
{
ast_manager_unregister("DataGet");
Modified: trunk/main/db.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/db.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/db.c (original)
+++ trunk/main/db.c Fri Aug 16 12:33:21 2013
@@ -982,7 +982,10 @@
return NULL;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void astdb_atexit(void)
{
ast_cli_unregister_multiple(cli_database, ARRAY_LEN(cli_database));
Modified: trunk/main/features.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/features.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/features.c (original)
+++ trunk/main/features.c Fri Aug 16 12:33:21 2013
@@ -1439,7 +1439,10 @@
return 0;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void features_shutdown(void)
{
ast_features_config_shutdown();
Modified: trunk/main/file.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/file.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/file.c (original)
+++ trunk/main/file.c Fri Aug 16 12:33:21 2013
@@ -343,7 +343,10 @@
return 0;
}
-/*! \internal \brief Close the file stream by canceling any pending read / write callbacks */
+/*!
+ * \internal
+ * \brief Close the file stream by canceling any pending read / write callbacks
+ */
static void filestream_close(struct ast_filestream *f)
{
enum ast_format_type format_type = AST_FORMAT_GET_TYPE(f->fmt->format.id);
Modified: trunk/main/format.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/format.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/format.c (original)
+++ trunk/main/format.c Fri Aug 16 12:33:21 2013
@@ -1071,7 +1071,10 @@
return 0;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void format_list_shutdown(void)
{
ast_rwlock_destroy(&format_list_array_lock);
@@ -1105,7 +1108,10 @@
return -1;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void format_attr_shutdown(void)
{
ast_cli_unregister_multiple(my_clis, ARRAY_LEN(my_clis));
Modified: trunk/main/indications.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/indications.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/indications.c (original)
+++ trunk/main/indications.c Fri Aug 16 12:33:21 2013
@@ -1149,7 +1149,10 @@
return 0;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void indications_shutdown(void)
{
ast_cli_unregister_multiple(cli_indications, ARRAY_LEN(cli_indications));
Modified: trunk/main/manager.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/manager.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/manager.c (original)
+++ trunk/main/manager.c Fri Aug 16 12:33:21 2013
@@ -7678,7 +7678,10 @@
#endif
-/*! \internal \brief Free a user record. Should already be removed from the list */
+/*!
+ * \internal
+ * \brief Free a user record. Should already be removed from the list
+ */
static void manager_free_user(struct ast_manager_user *user)
{
if (user->a1_hash) {
@@ -7696,7 +7699,10 @@
ast_free(user);
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void manager_shutdown(void)
{
struct ast_manager_user *user;
Modified: trunk/main/message.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/message.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/message.c (original)
+++ trunk/main/message.c Fri Aug 16 12:33:21 2013
@@ -1301,10 +1301,14 @@
}
}
-/*! \internal \brief Clean up other resources on Asterisk shutdown
+/*!
+ * \internal
+ * \brief Clean up other resources on Asterisk shutdown
+ *
* \note This does not include the msg_q_tp object, which must be disposed
* of prior to Asterisk checking for channel destruction in its shutdown
- * sequence. The atexit handlers are executed after this occurs. */
+ * sequence. The atexit handlers are executed after this occurs.
+ */
static void message_shutdown(void)
{
ast_custom_function_unregister(&msg_function);
Modified: trunk/main/pbx.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/pbx.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/pbx.c (original)
+++ trunk/main/pbx.c Fri Aug 16 12:33:21 2013
@@ -4841,7 +4841,10 @@
return "Unknown";
}
-/*! \internal \brief Check extension state for an extension by using hint */
+/*!
+ * \internal
+ * \brief Check extension state for an extension by using hint
+ */
static int internal_extension_state_extended(struct ast_channel *c, const char *context, const char *exten,
struct ao2_container *device_state_info)
{
@@ -5226,7 +5229,10 @@
}
}
-/*! \internal \brief Add watcher for extension states with destructor */
+/*!
+ * \internal
+ * \brief Add watcher for extension states with destructor
+ */
static int 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, int extended)
{
@@ -11431,8 +11437,12 @@
AST_DATA_ENTRY("asterisk/core/hints", &hints_data_provider),
};
-/*! \internal \brief Clean up resources on Asterisk shutdown.
- * \note Cleans up resources allocated in load_pbx */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown.
+ *
+ * \note Cleans up resources allocated in load_pbx
+ */
static void unload_pbx(void)
{
int x;
Modified: trunk/main/pickup.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/pickup.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/pickup.c (original)
+++ trunk/main/pickup.c Fri Aug 16 12:33:21 2013
@@ -383,7 +383,10 @@
return res;
}
-/*! \internal \brief Clean up resources on Asterisk shutdown */
+/*!
+ * \internal
+ * \brief Clean up resources on Asterisk shutdown
+ */
static void pickup_shutdown(void)
{
STASIS_MESSAGE_TYPE_CLEANUP(ast_call_pickup_type);
Modified: trunk/main/rtp_engine.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/rtp_engine.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/rtp_engine.c (original)
+++ trunk/main/rtp_engine.c Fri Aug 16 12:33:21 2013
@@ -1671,7 +1671,10 @@
return 0;
}
-/*! \internal \brief \ref stasis message payload for RTCP messages */
+/*!
+ * \internal
+ * \brief \ref stasis message payload for RTCP messages
+ */
struct rtcp_message_payload {
struct ast_channel_snapshot *snapshot; /*< The channel snapshot, if available */
struct ast_rtp_rtcp_report *report; /*< The RTCP report */
Modified: trunk/main/stasis_channels.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/stasis_channels.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/stasis_channels.c (original)
+++ trunk/main/stasis_channels.c Fri Aug 16 12:33:21 2013
@@ -138,7 +138,10 @@
return snapshot->name;
}
-/*! \internal \brief Hash function for \ref ast_channel_snapshot objects */
+/*!
+ * \internal
+ * \brief Hash function for \ref ast_channel_snapshot objects
+ */
static int channel_snapshot_hash_cb(const void *obj, const int flags)
{
const struct ast_channel_snapshot *snapshot = obj;
@@ -146,7 +149,10 @@
return ast_str_case_hash(name);
}
-/*! \internal \brief Comparison function for \ref ast_channel_snapshot objects */
+/*!
+ * \internal
+ * \brief Comparison function for \ref ast_channel_snapshot objects
+ */
static int channel_snapshot_cmp_cb(void *obj, void *arg, int flags)
{
struct ast_channel_snapshot *left = obj;
@@ -401,7 +407,10 @@
struct ast_json *blob; /*< A blob of JSON data */
};
-/*! \internal \brief Standard comparison function for \ref channel_role_snapshot objects */
+/*!
+ * \internal
+ * \brief Standard comparison function for \ref channel_role_snapshot objects
+ */
static int channel_role_single_cmp_cb(void *obj, void *arg, int flags)
{
struct channel_role_snapshot *left = obj;
@@ -410,7 +419,10 @@
return strcasecmp(left->role, match) ? 0 : (CMP_MATCH | CMP_STOP);
}
-/*! \internal \brief Multi comparison function for \ref channel_role_snapshot objects */
+/*!
+ * \internal
+ * \brief Multi comparison function for \ref channel_role_snapshot objects
+ */
static int channel_role_multi_cmp_cb(void *obj, void *arg, int flags)
{
struct channel_role_snapshot *left = obj;
@@ -419,7 +431,10 @@
return strcasecmp(left->role, match) ? 0 : (CMP_MATCH);
}
-/*! \internal \brief Hash function for \ref channel_role_snapshot objects */
+/*!
+ * \internal
+ * \brief Hash function for \ref channel_role_snapshot objects
+ */
static int channel_role_hash_cb(const void *obj, const int flags)
{
const struct channel_role_snapshot *snapshot = obj;
@@ -427,7 +442,10 @@
return ast_str_case_hash(name);
}
-/*! \internal \brief Destructor for \ref ast_multi_channel_blob objects */
+/*!
+ * \internal
+ * \brief Destructor for \ref ast_multi_channel_blob objects
+ */
static void multi_channel_blob_dtor(void *obj)
{
struct ast_multi_channel_blob *multi_blob = obj;
Modified: trunk/main/xmldoc.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/xmldoc.c?view=diff&rev=396857&r1=396856&r2=396857
==============================================================================
--- trunk/main/xmldoc.c (original)
+++ trunk/main/xmldoc.c Fri Aug 16 12:33:21 2013
@@ -45,13 +45,17 @@
/*! \brief Default documentation language. */
static const char default_documentation_language[] = "en_US";
-/*! \brief Number of columns to print when showing the XML documentation with a
- * 'core show application/function *' CLI command. Used in text wrapping.*/
+/*!
+ * \brief Number of columns to print when showing the XML documentation with a
+ * 'core show application/function *' CLI command. Used in text wrapping.
+ */
static const int xmldoc_text_columns = 74;
-/*! \brief This is a value that we will use to let the wrapping mechanism move the cursor
+/*!
+ * \brief This is a value that we will use to let the wrapping mechanism move the cursor
* backward and forward xmldoc_max_diff positions before cutting the middle of a
- * word, trying to find a space or a \n. */
+ * word, trying to find a space or a \n.
+ */
static const int xmldoc_max_diff = 5;
/*! \brief XML documentation language. */
@@ -111,11 +115,14 @@
{ "warning", "<warning>WARNING!!!:</warning> ", "" }
};
-/*! \internal
- * \brief Calculate the space in bytes used by a format string
- * that will be passed to a sprintf function.
- * \param postbr The format string to use to calculate the length.
- * \retval The postbr length.
+/*!
+ * \internal
+ * \brief Calculate the space in bytes used by a format string
+ * that will be passed to a sprintf function.
+ *
+ * \param postbr The format string to use to calculate the length.
+ *
+ * \retval The postbr length.
*/
static int xmldoc_postbrlen(const char *postbr)
{
@@ -136,12 +143,14 @@
return postbrreallen;
}
-/*! \internal
- * \brief Setup postbr to be used while wrapping the text.
- * Add to postbr array all the spaces and tabs at the beginning of text.
- * \param postbr output array.
- * \param len text array length.
- * \param text Text with format string before the actual string.
+/*!
+ * \internal
+ * \brief Setup postbr to be used while wrapping the text.
+ * Add to postbr array all the spaces and tabs at the beginning of text.
+ *
+ * \param postbr output array.
+ * \param len text array length.
+ * \param text Text with format string before the actual string.
*/
static void xmldoc_setpostbr(char *postbr, size_t len, const char *text)
{
@@ -161,15 +170,18 @@
postbr[postbrlen] = '\0';
}
-/*! \internal
- * \brief Try to find a space or a break in text starting at currentpost
+/*!
+ * \internal
+ * \brief Try to find a space or a break in text starting at currentpost
* and moving at most maxdiff positions.
* Helper for xmldoc_string_wrap().
- * \param text Input string where it will search.
- * \param currentpos Current position within text.
- * \param maxdiff Not move more than maxdiff inside text.
- * \retval 1 if a space or break is found inside text while moving.
- * \retval 0 if no space or break is found.
+ *
+ * \param text Input string where it will search.
+ * \param currentpos Current position within text.
+ * \param maxdiff Not move more than maxdiff inside text.
+ *
+ * \retval 1 if a space or break is found inside text while moving.
+ * \retval 0 if no space or break is found.
*/
static int xmldoc_wait_nextspace(const char *text, int currentpos, int maxdiff)
{
@@ -200,16 +212,19 @@
return 0;
}
-/*! \internal
- * \brief Helper function for xmldoc_string_wrap().
- * Try to found a space or a break inside text moving backward
- * not more than maxdiff positions.
- * \param text The input string where to search for a space.
- * \param currentpos The current cursor position.
- * \param maxdiff The max number of positions to move within text.
- * \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
- * \retval > 0 If a space or a break is found, and the result is the position relative to
- * currentpos.
+/*!
+ * \internal
+ * \brief Helper function for xmldoc_string_wrap().
+ * Try to found a space or a break inside text moving backward
+ * not more than maxdiff positions.
+ *
+ * \param text The input string where to search for a space.
+ * \param currentpos The current cursor position.
+ * \param maxdiff The max number of positions to move within text.
+ *
+ * \retval 0 If no space is found (Notice that text[currentpos] is not a space or a break)
+ * \retval > 0 If a space or a break is found, and the result is the position relative to
+ * currentpos.
*/
static int xmldoc_foundspace_backward(const char *text, int currentpos, int maxdiff)
{
@@ -232,13 +247,16 @@
return 0;
}
-/*! \internal
- * \brief Justify a text to a number of columns.
- * \param text Input text to be justified.
- * \param columns Number of columns to preserve in the text.
- * \param maxdiff Try to not cut a word when goinf down.
- * \retval NULL on error.
- * \retval The wrapped text.
+/*!
+ * \internal
+ * \brief Justify a text to a number of columns.
+ *
+ * \param text Input text to be justified.
+ * \param columns Number of columns to preserve in the text.
+ * \param maxdiff Try to not cut a word when goinf down.
+ *
+ * \retval NULL on error.
+ * \retval The wrapped text.
*/
static char *xmldoc_string_wrap(const char *text, int columns, int maxdiff)
{
@@ -427,11 +445,13 @@
return wrapped;
}
-/*! \internal
- * \brief Cleanup spaces and tabs after a \n
- * \param text String to be cleaned up.
- * \param output buffer (not already allocated).
- * \param lastspaces Remove last spaces in the string.
+/*!
+ * \internal
+ * \brief Cleanup spaces and tabs after a \n
+ *
+ * \param text String to be cleaned up.
+ * \param output buffer (not already allocated).
+ * \param lastspaces Remove last spaces in the string.
*/
static void xmldoc_string_cleanup(const char *text, struct ast_str **output, int lastspaces)
{
@@ -470,11 +490,14 @@
}
}
-/*! \internal
+/*!
+ * \internal
* \brief Check if the given attribute on the given node matches the given value.
+ *
* \param node the node to match
* \param attr the name of the attribute
* \param value the expected value of the attribute
+ *
* \retval true if the given attribute contains the given value
* \retval false if the given attribute does not exist or does not contain the given value
*/
@@ -486,16 +509,19 @@
return match;
}
-/*! \internal
- * \brief Get the application/function node for 'name' application/function with language 'language'
- * and module 'module' if we don't find any, get the first application
- * with 'name' no matter which language or module.
- * \param type 'application', 'function', ...
- * \param name Application or Function name.
- * \param module Module item is in.
- * \param language Try to get this language (if not found try with en_US)
- * \retval NULL on error.
- * \retval A node of type ast_xml_node.
+/*!
+ * \internal
+ * \brief Get the application/function node for 'name' application/function with language 'language'
+ * and module 'module' if we don't find any, get the first application
+ * with 'name' no matter which language or module.
+ *
+ * \param type 'application', 'function', ...
+ * \param name Application or Function name.
+ * \param module Module item is in.
+ * \param language Try to get this language (if not found try with en_US)
+ *
+ * \retval NULL on error.
+ * \retval A node of type ast_xml_node.
*/
static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)
{
@@ -568,14 +594,16 @@
return node;
}
-/*! \internal
- * \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
- * and based on the reverse value it makes use of fmt to print the parameter list inside the
- * realloced buffer (syntax).
- * \param reverse We are going backwards while generating the syntax?
- * \param len Current length of 'syntax' buffer.
- * \param syntax Output buffer for the concatenated values.
- * \param fmt A format string that will be used in a sprintf call.
+/*!
+ * \internal
+ * \brief Helper function used to build the syntax, it allocates the needed buffer (or reallocates it),
+ * and based on the reverse value it makes use of fmt to print the parameter list inside the
+ * realloced buffer (syntax).
+ *
+ * \param reverse We are going backwards while generating the syntax?
+ * \param len Current length of 'syntax' buffer.
+ * \param syntax Output buffer for the concatenated values.
+ * \param fmt A format string that will be used in a sprintf call.
*/
static void __attribute__((format(printf, 4, 5))) xmldoc_reverse_helper(int reverse, int *len, char **syntax, const char *fmt, ...)
{
@@ -616,12 +644,15 @@
ast_free(tmpfmt);
}
-/*! \internal
- * \brief Check if the passed node has 'what' tags inside it.
- * \param node Root node to search 'what' elements.
- * \param what node name to search inside node.
- * \retval 1 If a 'what' element is found inside 'node'.
- * \retval 0 If no 'what' is found inside 'node'.
+/*!
+ * \internal
+ * \brief Check if the passed node has 'what' tags inside it.
+ *
+ * \param node Root node to search 'what' elements.
+ * \param what node name to search inside node.
+ *
+ * \retval 1 If a 'what' element is found inside 'node'.
+ * \retval 0 If no 'what' is found inside 'node'.
*/
static int xmldoc_has_inside(struct ast_xml_node *fixnode, const char *what)
{
@@ -635,11 +666,14 @@
return 0;
}
-/*! \internal
- * \brief Check if the passed node has at least one node inside it.
- * \param node Root node to search node elements.
- * \retval 1 If a node element is found inside 'node'.
- * \retval 0 If no node is found inside 'node'.
+/*!
+ * \internal
+ * \brief Check if the passed node has at least one node inside it.
+ *
+ * \param node Root node to search node elements.
+ *
+ * \retval 1 If a node element is found inside 'node'.
+ * \retval 0 If no node is found inside 'node'.
*/
static int xmldoc_has_nodes(struct ast_xml_node *fixnode)
{
@@ -653,11 +687,14 @@
return 0;
}
-/*! \internal
- * \brief Check if the passed node has at least one specialtag.
- * \param node Root node to search "specialtags" elements.
- * \retval 1 If a "specialtag" element is found inside 'node'.
- * \retval 0 If no "specialtag" is found inside 'node'.
+/*!
+ * \internal
+ * \brief Check if the passed node has at least one specialtag.
+ *
+ * \param node Root node to search "specialtags" elements.
+ *
+ * \retval 1 If a "specialtag" element is found inside 'node'.
+ * \retval 0 If no "specialtag" is found inside 'node'.
*/
static int xmldoc_has_specialtags(struct ast_xml_node *fixnode)
{
@@ -674,15 +711,18 @@
return 0;
}
-/*! \internal
- * \brief Build the syntax for a specified starting node.
- * \param rootnode A pointer to the ast_xml root node.
- * \param rootname Name of the application, function, option, etc. to build the syntax.
- * \param childname The name of each parameter node.
- * \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
- * \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
- * \retval NULL on error.
- * \retval An ast_malloc'ed string with the syntax generated.
+/*!
+ * \internal
+ * \brief Build the syntax for a specified starting node.
+ *
+ * \param rootnode A pointer to the ast_xml root node.
+ * \param rootname Name of the application, function, option, etc. to build the syntax.
+ * \param childname The name of each parameter node.
+ * \param printparenthesis Boolean if we must print parenthesis if not parameters are found in the rootnode.
+ * \param printrootname Boolean if we must print the rootname before the syntax and parenthesis at the begining/end.
+ *
+ * \retval NULL on error.
+ * \retval An ast_malloc'ed string with the syntax generated.
*/
static char *xmldoc_get_syntax_fun(struct ast_xml_node *rootnode, const char *rootname, const char *childname, int printparenthesis, int printrootname)
{
@@ -919,12 +959,14 @@
#undef MP
}
-/*! \internal
- * \brief Parse an enumlist inside a <parameter> to generate a COMMAND
- * syntax.
- * \param fixnode A pointer to the <enumlist> node.
- * \retval {<unknown>} on error.
- * \retval A string inside brackets {} with the enum's separated by pipes |.
+/*!
+ * \internal
+ * \brief Parse an enumlist inside a <parameter> to generate a COMMAND syntax.
+ *
+ * \param fixnode A pointer to the <enumlist> node.
+ *
+ * \retval {<unknown>} on error.
+ * \retval A string inside brackets {} with the enum's separated by pipes |.
*/
static char *xmldoc_parse_cmd_enumlist(struct ast_xml_node *fixnode)
{
@@ -965,13 +1007,16 @@
return ret;
}
-/*! \internal
- * \brief Generate a syntax of COMMAND type.
- * \param fixnode The <syntax> node pointer.
- * \param name The name of the 'command'.
- * \param printname Print the name of the command before the paramters?
- * \retval On error, return just 'name'.
- * \retval On success return the generated syntax.
+/*!
+ * \internal
+ * \brief Generate a syntax of COMMAND type.
+ *
+ * \param fixnode The <syntax> node pointer.
+ * \param name The name of the 'command'.
+ * \param printname Print the name of the command before the paramters?
+ *
+ * \retval On error, return just 'name'.
+ * \retval On success return the generated syntax.
*/
static char *xmldoc_get_syntax_cmd(struct ast_xml_node *fixnode, const char *name, int printname)
{
@@ -1068,13 +1113,16 @@
return ret;
}
-/*! \internal
- * \brief Generate an AMI action/event syntax.
- * \param fixnode The manager action/event node pointer.
- * \param name The name of the manager action/event.
- * \param manager_type "Action" or "Event"
- * \retval The generated syntax.
- * \retval NULL on error.
+/*!
+ * \internal
+ * \brief Generate an AMI action/event syntax.
+ *
+ * \param fixnode The manager action/event node pointer.
+ * \param name The name of the manager action/event.
+ * \param manager_type "Action" or "Event"
+ *
+ * \retval The generated syntax.
+ * \retval NULL on error.
*/
static char *xmldoc_get_syntax_manager(struct ast_xml_node *fixnode, const char *name, const char *manager_type)
{
@@ -1219,10 +1267,13 @@
{ "agi", COMMAND_SYNTAX },
};
-/*! \internal
- * \brief Get syntax type based on type of node.
- * \param type Type of node.
- * \retval The type of syntax to generate based on the type of node.
+/*!
+ * \internal
+ * \brief Get syntax type based on type of node.
+ *
+ * \param type Type of node.
+ *
+ * \retval The type of syntax to generate based on the type of node.
*/
static enum syntaxtype xmldoc_get_syntax_type(const char *type)
{
@@ -1246,8 +1297,8 @@
* \note This method exists for when you already have the node. This
* prevents having to lock the documentation tree twice
*
- * \returns A malloc'd character pointer to the syntax of the item
- * \returns NULL on failure
+ * \retval A malloc'd character pointer to the syntax of the item
+ * \retval NULL on failure
*
* \since 11
*/
@@ -1300,18 +1351,21 @@
return _ast_xmldoc_build_syntax(node, type, name);
}
-/*! \internal
- * \brief Parse common internal elements. This includes paragraphs, special
- * tags, and information nodes.
- * \param node The element to parse
- * \param tabs Add this string before the content of the parsed element.
- * \param posttabs Add this string after the content of the parsed element.
- * \param buffer This must be an already allocated ast_str. It will be used to
- * store the result (if something has already been placed in the
- * buffer, the parsed elements will be appended)
- * \retval 1 if any data was appended to the buffer
- * \retval 2 if the data appended to the buffer contained a text paragraph
- * \retval 0 if no data was appended to the buffer
+/*!
+ * \internal
+ * \brief Parse common internal elements. This includes paragraphs, special
+ * tags, and information nodes.
+ *
+ * \param node The element to parse
+ * \param tabs Add this string before the content of the parsed element.
+ * \param posttabs Add this string after the content of the parsed element.
+ * \param buffer This must be an already allocated ast_str. It will be used to
+ * store the result (if something has already been placed in the
+ * buffer, the parsed elements will be appended)
+ *
+ * \retval 1 if any data was appended to the buffer
+ * \retval 2 if the data appended to the buffer contained a text paragraph
+ * \retval 0 if no data was appended to the buffer
*/
static int xmldoc_parse_common_elements(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
{
@@ -1320,17 +1374,20 @@
|| xmldoc_parse_info(node, tabs, posttabs, buffer));
}
-/*! \internal
- * \brief Parse a <para> element.
- * \param node The <para> element pointer.
- * \param tabs Added this string before the content of the <para> element.
- * \param posttabs Added this string after the content of the <para> element.
- * \param buffer This must be an already allocated ast_str. It will be used
- * to store the result (if already has something it will be appended to the current
- * string).
- * \retval 1 If 'node' is a named 'para'.
- * \retval 2 If data is appended in buffer.
- * \retval 0 on error.
+/*!
+ * \internal
+ * \brief Parse a <para> element.
+ *
+ * \param node The <para> element pointer.
+ * \param tabs Added this string before the content of the <para> element.
+ * \param posttabs Added this string after the content of the <para> element.
+ * \param buffer This must be an already allocated ast_str. It will be used
+ * to store the result (if already has something it will be appended to the current
+ * string).
+ *
+ * \retval 1 If 'node' is a named 'para'.
+ * \retval 2 If data is appended in buffer.
+ * \retval 0 on error.
*/
static int xmldoc_parse_para(struct ast_xml_node *node, const char *tabs, const char *posttabs, struct ast_str **buffer)
{
@@ -1376,15 +1433,18 @@
return ret;
}
-/*! \internal
- * \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
- * \param fixnode special tag node pointer.
- * \param tabs put tabs before printing the node content.
- * \param posttabs put posttabs after printing node content.
- * \param buffer Output buffer, the special tags will be appended here.
- * \retval 0 if no special element is parsed.
- * \retval 1 if a special element is parsed (data is appended to buffer).
- * \retval 2 if a special element is parsed and also a <para> element is parsed inside the specialtag.
+/*!
+ * \internal
+ * \brief Parse special elements defined in 'struct special_tags' special elements must have a <para> element inside them.
+ *
+ * \param fixnode special tag node pointer.
+ * \param tabs put tabs before printing the node content.
+ * \param posttabs put posttabs after printing node content.
[... 1247 lines stripped ...]
More information about the asterisk-commits
mailing list