<p>Friendly Automation <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/17522">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Kevin Harwell: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">app: Fix for Doxygen.<br><br>ASTERISK-29752<br><br>Change-Id: If40cbd01d47a6cfd620b18206dedb8460216c8af<br>---<br>M include/asterisk/app.h<br>M main/app.c<br>2 files changed, 40 insertions(+), 56 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/include/asterisk/app.h b/include/asterisk/app.h</span><br><span>index 560f852..3fed048 100644</span><br><span>--- a/include/asterisk/app.h</span><br><span>+++ b/include/asterisk/app.h</span><br><span>@@ -42,7 +42,8 @@</span><br><span> /* IVR stuff */</span><br><span> </span><br><span> /*! \brief Callback function for IVR</span><br><span style="color: hsl(0, 100%, 40%);">- \return returns 0 on completion, -1 on hangup or digit if interrupted</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval 0 on completion.</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval -1 on hangup or digit if interrupted.</span><br><span> */</span><br><span> typedef int (ast_ivr_callback)(struct ast_channel *chan, char *option, void *cbdata);</span><br><span> </span><br><span>@@ -56,7 +57,7 @@</span><br><span> AST_ACTION_MENU, /*!< adata is a pointer to an ast_ivr_menu */</span><br><span> AST_ACTION_REPEAT, /*!< adata is max # of repeats, cast to a pointer */</span><br><span> AST_ACTION_RESTART, /*!< adata is like repeat, but resets repeats to 0 */</span><br><span style="color: hsl(0, 100%, 40%);">- AST_ACTION_TRANSFER, /*!< adata is a string with exten\verbatim[@context]\endverbatim */</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_ACTION_TRANSFER, /*!< adata is a string with exten[\@context] */</span><br><span> AST_ACTION_WAITOPTION, /*!< adata is a timeout, or 0 for defaults */</span><br><span> AST_ACTION_NOOP, /*!< adata is unused */</span><br><span> AST_ACTION_BACKLIST, /*!< adata is list of files separated by ; allows interruption */</span><br><span>@@ -118,7 +119,10 @@</span><br><span> };</span><br><span> </span><br><span> /*! \brief Runs an IVR menu</span><br><span style="color: hsl(0, 100%, 40%);">- \return returns 0 on successful completion, -1 on hangup, or -2 on user error in menu */</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval 0 on successful completion.</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval -1 on hangup.</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval -2 on user error in menu.</span><br><span style="color: hsl(120, 100%, 40%);">+*/</span><br><span> int ast_ivr_menu_run(struct ast_channel *c, struct ast_ivr_menu *menu, void *cbdata);</span><br><span> </span><br><span> /*! \brief Plays a stream and gets DTMF data from a channel</span><br><span>@@ -234,7 +238,7 @@</span><br><span> * \details</span><br><span> * Fills in the optional context and exten from the given channel.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval New-args Gosub argument string on success. Must be freed.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return New-args Gosub argument string on success. Must be freed.</span><br><span> * \retval NULL on error.</span><br><span> */</span><br><span> const char *(*expand_sub_args)(struct ast_channel *chan, const char *args);</span><br><span>@@ -258,7 +262,7 @@</span><br><span> * \details</span><br><span> * Fills in the optional context and exten from the given channel.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval New-args Gosub argument string on success. Must be freed.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return New-args Gosub argument string on success. Must be freed.</span><br><span> * \retval NULL on error.</span><br><span> */</span><br><span> const char *ast_app_expand_sub_args(struct ast_channel *chan, const char *args);</span><br><span>@@ -351,7 +355,7 @@</span><br><span> /*!</span><br><span> * \brief Determines if the given folder has messages.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param mailboxes Comma or & delimited list of mailboxes (user@context).</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param mailboxes Comma or & delimited list of mailboxes (user\@context).</span><br><span> * If no context is found, uses 'default' for the context.</span><br><span> * \param folder The folder to look in. Default is INBOX if not provided.</span><br><span> *</span><br><span>@@ -363,7 +367,7 @@</span><br><span> /*!</span><br><span> * \brief Gets the number of messages that exist for the mailbox list.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param mailboxes Comma or space delimited list of mailboxes (user@context).</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param mailboxes Comma or space delimited list of mailboxes (user\@context).</span><br><span> * If no context is found, uses 'default' for the context.</span><br><span> * \param newmsgs Where to put the count of new messages. (Can be NULL)</span><br><span> * \param oldmsgs Where to put the count of old messages. (Can be NULL)</span><br><span>@@ -380,7 +384,7 @@</span><br><span> /*!</span><br><span> * \brief Gets the number of messages that exist for the mailbox list.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param mailboxes Comma or space delimited list of mailboxes (user@context).</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param mailboxes Comma or space delimited list of mailboxes (user\@context).</span><br><span> * If no context is found, uses 'default' for the context.</span><br><span> * \param urgentmsgs Where to put the count of urgent messages. (Can be NULL)</span><br><span> * \param newmsgs Where to put the count of new messages. (Can be NULL)</span><br><span>@@ -415,7 +419,7 @@</span><br><span> * \param mailbox_id The mailbox name.</span><br><span> *</span><br><span> * \retval 0 Name played without interruption</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval dtmf ASCII value of the DTMF which interrupted playback.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return dtmf ASCII value of the DTMF which interrupted playback.</span><br><span> * \retval -1 Unable to locate mailbox or hangup occurred.</span><br><span> */</span><br><span> typedef int (ast_sayname_fn)(struct ast_channel *chan, const char *mailbox_id);</span><br><span>@@ -444,8 +448,8 @@</span><br><span> /*!</span><br><span> * \brief Create a snapshot of a mailbox which contains information about every msg.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param user The user part of user@context.</span><br><span style="color: hsl(0, 100%, 40%);">- * \param context The context part of user@context. Must be explicit.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param user The user part of user\@context.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param context The context part of user\@context. Must be explicit.</span><br><span> * \param folder When not NULL only msgs from the specified folder will be included.</span><br><span> * \param descending list the msgs in descending order rather than ascending order.</span><br><span> * \param sort_val What to sort in the snapshot.</span><br><span>@@ -455,7 +459,7 @@</span><br><span> *</span><br><span> * \note Only used by voicemail unit tests.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval snapshot on success</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return snapshot on success</span><br><span> * \retval NULL on failure</span><br><span> */</span><br><span> typedef struct ast_vm_mailbox_snapshot *(ast_vm_mailbox_snapshot_create_fn)(const char *user,</span><br><span>@@ -607,9 +611,7 @@</span><br><span> /*!</span><br><span> * \brief Unregister the specified voicemail provider</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param The module name of the provider to unregister</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span style="color: hsl(0, 100%, 40%);">- * \return Nothing</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param module_name The module name of the provider to unregister</span><br><span> */</span><br><span> void ast_vm_unregister(const char *module_name);</span><br><span> </span><br><span>@@ -677,9 +679,7 @@</span><br><span> * \brief Unregister the specified voicemail greeter provider</span><br><span> * \since 13.0.0</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param The module name of the provider to unregister</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span style="color: hsl(0, 100%, 40%);">- * \return Nothing</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param module_name The module name of the provider to unregister</span><br><span> */</span><br><span> void ast_vm_greeter_unregister(const char *module_name);</span><br><span> </span><br><span>@@ -732,7 +732,8 @@</span><br><span> * \param[out] urgentmsgs the urgent message count</span><br><span> * \param[out] newmsgs the new message count</span><br><span> * \param[out] oldmsgs the old message count</span><br><span style="color: hsl(0, 100%, 40%);">- * \return Returns 0 for success, negative upon error</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 0 for success</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval negative upon error</span><br><span> * \since 1.6.1</span><br><span> */</span><br><span> int ast_app_inboxcount2(const char *mailboxes, int *urgentmsgs, int *newmsgs, int *oldmsgs);</span><br><span>@@ -771,15 +772,16 @@</span><br><span> /*!</span><br><span> * \brief Create a snapshot of a mailbox which contains information about every msg.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \param mailbox, the mailbox to look for</span><br><span style="color: hsl(0, 100%, 40%);">- * \param context, the context to look for the mailbox in</span><br><span style="color: hsl(0, 100%, 40%);">- * \param folder, OPTIONAL. When not NULL only msgs from the specified folder will be included.</span><br><span style="color: hsl(0, 100%, 40%);">- * \param descending, list the msgs in descending order rather than ascending order.</span><br><span style="color: hsl(0, 100%, 40%);">- * \param combine_INBOX_and_OLD, When this argument is set, The OLD folder will be represented</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param mailbox the mailbox to look for</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param context the context to look for the mailbox in</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param folder OPTIONAL. When not NULL only msgs from the specified folder will be included.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param descending list the msgs in descending order rather than ascending order.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sort_val What to sort in the snapshot.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param combine_INBOX_and_OLD When this argument is set, The OLD folder will be represented</span><br><span> * in the INBOX folder of the snapshot. This allows the snapshot to represent the</span><br><span> * OLD and INBOX messages in sorted order merged together.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval snapshot on success</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return snapshot on success</span><br><span> * \retval NULL on failure</span><br><span> */</span><br><span> struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_create(const char *mailbox,</span><br><span>@@ -980,8 +982,6 @@</span><br><span> *</span><br><span> * \pre This must only be called by threads that are not the channel's</span><br><span> * media handler thread.</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span style="color: hsl(0, 100%, 40%);">- * \return Nothing</span><br><span> */</span><br><span> void ast_dtmf_stream_external(struct ast_channel *chan, const char *digits, int between, unsigned int duration);</span><br><span> </span><br><span>@@ -1405,7 +1405,8 @@</span><br><span> \param flags The flag structure to have option flags set</span><br><span> \param args The array of argument pointers to hold arguments found</span><br><span> \param optstr The string containing the options to be parsed</span><br><span style="color: hsl(0, 100%, 40%);">- \return zero for success, non-zero if an error occurs</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval zero for success</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval non-zero if an error occurs</span><br><span> \sa AST_APP_OPTIONS</span><br><span> */</span><br><span> int ast_app_parse_options(const struct ast_app_option *options, struct ast_flags *flags, char **args, char *optstr);</span><br><span>@@ -1416,7 +1417,8 @@</span><br><span> \param flags The 64-bit flag structure to have option flags set</span><br><span> \param args The array of argument pointers to hold arguments found</span><br><span> \param optstr The string containing the options to be parsed</span><br><span style="color: hsl(0, 100%, 40%);">- \return zero for success, non-zero if an error occurs</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval zero for success</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval non-zero if an error occurs</span><br><span> \sa AST_APP_OPTIONS</span><br><span> */</span><br><span> int ast_app_parse_options64(const struct ast_app_option *options, struct ast_flags64 *flags, char **args, char *optstr);</span><br><span>@@ -1430,7 +1432,9 @@</span><br><span> void ast_app_options2str64(const struct ast_app_option *options, struct ast_flags64 *flags, char *buf, size_t len);</span><br><span> </span><br><span> /*! \brief Present a dialtone and collect a certain length extension.</span><br><span style="color: hsl(0, 100%, 40%);">- \return Returns 1 on valid extension entered, -1 on hangup, or 0 on invalid extension.</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval 1 if extension exists</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval 0 if extension does not exist</span><br><span style="color: hsl(120, 100%, 40%);">+ \retval -1 on hangup</span><br><span> \note Note that if 'collect' holds digits already, new digits will be appended, so be sure it's initialized properly */</span><br><span> int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout);</span><br><span> </span><br><span>@@ -1492,7 +1496,7 @@</span><br><span> </span><br><span> /*!</span><br><span> * \brief Get the \ref stasis topic for queue messages</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval The topic structure for queue messages</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return The topic structure for queue messages</span><br><span> * \retval NULL if it has not been allocated</span><br><span> * \since 12</span><br><span> */</span><br><span>@@ -1501,7 +1505,7 @@</span><br><span> /*!</span><br><span> * \brief Get the \ref stasis topic for queue messages for a particular queue name</span><br><span> * \param queuename The name for which to get the topic</span><br><span style="color: hsl(0, 100%, 40%);">- * \retval The topic structure for queue messages for a given name</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return The topic structure for queue messages for a given name</span><br><span> * \retval NULL if it failed to be found or allocated</span><br><span> * \since 12</span><br><span> */</span><br><span>diff --git a/main/app.c b/main/app.c</span><br><span>index 68a51dc..aff690e 100644</span><br><span>--- a/main/app.c</span><br><span>+++ b/main/app.c</span><br><span>@@ -132,8 +132,6 @@</span><br><span> * \param size</span><br><span> * \param maxlen</span><br><span> * \param timeout timeout in milliseconds</span><br><span style="color: hsl(0, 100%, 40%);">- *</span><br><span style="color: hsl(0, 100%, 40%);">- * \return 0 if extension does not exist, 1 if extension exists</span><br><span> */</span><br><span> int ast_app_dtget(struct ast_channel *chan, const char *context, char *collect, size_t size, int maxlen, int timeout)</span><br><span> {</span><br><span>@@ -185,30 +183,11 @@</span><br><span> return res;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-/*!</span><br><span style="color: hsl(0, 100%, 40%);">- * \brief ast_app_getdata</span><br><span style="color: hsl(0, 100%, 40%);">- * \param c The channel to read from</span><br><span style="color: hsl(0, 100%, 40%);">- * \param prompt The file to stream to the channel</span><br><span style="color: hsl(0, 100%, 40%);">- * \param s The string to read in to. Must be at least the size of your length</span><br><span style="color: hsl(0, 100%, 40%);">- * \param maxlen How many digits to read (maximum)</span><br><span style="color: hsl(0, 100%, 40%);">- * \param timeout set timeout to 0 for "standard" timeouts. Set timeout to -1 for</span><br><span style="color: hsl(0, 100%, 40%);">- * "ludicrous time" (essentially never times out)</span><br><span style="color: hsl(0, 100%, 40%);">- */</span><br><span> enum ast_getdata_result ast_app_getdata(struct ast_channel *c, const char *prompt, char *s, int maxlen, int timeout)</span><br><span> {</span><br><span> return ast_app_getdata_terminator(c, prompt, s, maxlen, timeout, NULL);</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-/*!</span><br><span style="color: hsl(0, 100%, 40%);">- * \brief ast_app_getdata</span><br><span style="color: hsl(0, 100%, 40%);">- * \param c The channel to read from</span><br><span style="color: hsl(0, 100%, 40%);">- * \param prompt The file to stream to the channel</span><br><span style="color: hsl(0, 100%, 40%);">- * \param s The string to read in to. Must be at least the size of your length</span><br><span style="color: hsl(0, 100%, 40%);">- * \param maxlen How many digits to read (maximum)</span><br><span style="color: hsl(0, 100%, 40%);">- * \param timeout set timeout to 0 for "standard" timeouts. Set timeout to -1 for</span><br><span style="color: hsl(0, 100%, 40%);">- * "ludicrous time" (essentially never times out)</span><br><span style="color: hsl(0, 100%, 40%);">- * \param terminator A string of characters that may be used as terminators to end input. Default if NULL is "#"</span><br><span style="color: hsl(0, 100%, 40%);">- */</span><br><span> enum ast_getdata_result ast_app_getdata_terminator(struct ast_channel *c, const char *prompt, char *s,</span><br><span> int maxlen, int timeout, char *terminator)</span><br><span> {</span><br><span>@@ -1424,11 +1403,11 @@</span><br><span> /*!</span><br><span> * \brief Construct a silence frame of the same duration as \a orig.</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * The \a orig frame must be \ref AST_FORMAT_SLINEAR.</span><br><span style="color: hsl(120, 100%, 40%);">+ * The \a orig frame must be \ref ast_format_slin.</span><br><span> *</span><br><span> * \param orig Frame as basis for silence to generate.</span><br><span> * \return New frame of silence; free with ast_frfree().</span><br><span style="color: hsl(0, 100%, 40%);">- * \return \c NULL on error.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL on error.</span><br><span> */</span><br><span> static struct ast_frame *make_silence(const struct ast_frame *orig)</span><br><span> {</span><br><span>@@ -1473,7 +1452,7 @@</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span style="color: hsl(0, 100%, 40%);">- * \brief Sets a channel's read format to \ref AST_FORMAT_SLINEAR, recording</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Sets a channel's read format to \ref ast_format_slin, recording</span><br><span> * its original format.</span><br><span> *</span><br><span> * \param chan Channel to modify.</span><br><span>@@ -1510,6 +1489,7 @@</span><br><span> * \param acceptdtmf DTMF digits that will end the recording.</span><br><span> * \param canceldtmf DTMF digits that will cancel the recording.</span><br><span> * \param skip_confirmation_sound If true, don't play auth-thankyou at end. Nice for custom recording prompts in apps.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param if_exists</span><br><span> *</span><br><span> * \retval -1 failure or hangup</span><br><span> * \retval 'S' Recording ended from silence timeout</span><br><span></span><br></pre><div style="white-space:pre-wrap"></div><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/17522">change 17522</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/17522"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 18 </div>
<div style="display:none"> Gerrit-Change-Id: If40cbd01d47a6cfd620b18206dedb8460216c8af </div>
<div style="display:none"> Gerrit-Change-Number: 17522 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: Alexander Traud <pabstraud@compuserve.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Kevin Harwell <kharwell@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>