Doxygen Updates - janitor work

Doxygen updates including mistakes, misspellings, missing parameters, updates for Doxygen style.  Some missing txt file links are removed but their content or essense will be included in some later updates.  A majority of the txt files were removed in the 1.6 era but never noted. The HR and EXTREF are simple changes that make the documentation more compatable with more versions of Doxygen.

Further updates coming.

(issue ASTERISK-20259)


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

15 files changed, 90 insertions, 90 deletions

diff --git a/include/asterisk/acl.h b/include/asterisk/acl.h
index 0dfb47f08..50510a765 100644
--- a/include/asterisk/acl.h
+++ b/include/asterisk/acl.h
@@ -189,7 +189,7 @@ enum ast_acl_sense ast_apply_ha(const struct ast_ha *ha, const struct ast_sockad
  * contained in the acl container. It will deny if any of the ast_ha lists
  * fail, and it will pass only if all of the rules pass.
  *
- * \param acl The head of the list of ACLs to evaluate
+ * \param acl_list The head of the list of ACLs to evaluate
  * \param addr An ast_sockaddr whose address is considered when matching rules
  * \param purpose Context for which the ACL is being applied - Establishes purpose of a notice when rejected
  *
diff --git a/include/asterisk/app.h b/include/asterisk/app.h
index d10a0a667..cdc40e7d0 100644
--- a/include/asterisk/app.h
+++ b/include/asterisk/app.h
@@ -331,6 +331,9 @@ typedef void (ast_vm_msg_play_cb)(struct ast_channel *chan, const char *playfile
 
 /*!
  * \brief Set voicemail function callbacks
+ *
+ * \param copy_recording_to_vm_func, vm_index_to_foldername, vm_mailbox_snapshot_create
+ * \param vm_mailbox_snapshot_destroy, vm_msg_move, vm_msg_remove, vm_msg_forward, vm_msg_play
  * \param[in] has_voicemail_func set function pointer
  * \param[in] inboxcount_func set function pointer
  * \param[in] inboxcount2_func set function pointer
@@ -411,7 +414,10 @@ int ast_app_has_voicemail(const char *mailbox, const char *folder);
 /*!
  * \brief Determine number of new/old messages in a mailbox
  * \since 1.0
- * \param[in] mailbox Mailbox specification in the format mbox[@context][&mbox2[@context2]][...]
+ * \param[in] mailbox Mailbox specification in the format
+ * 	/code
+ *	 mbox[\@context][&mbox2[\@context2]][...]
+ *	/code
  * \param[out] newmsgs Number of messages in the "INBOX" folder.  Includes number of messages in the "Urgent" folder, if any.
  * \param[out] oldmsgs Number of messages in the "Old" folder.
  * \retval 0 Success
@@ -495,7 +501,7 @@ struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_destroy(struct ast_vm_ma
  * \param context The voicemail context for the mailbox
  * \param num_msgs The number of messages to move
  * \param oldfolder The folder from where messages should be moved
- * \param old_msg_nums The message IDs of the messages to move
+ * \param old_msg_ids The message IDs of the messages to move
  * \param newfolder The folder to which messages should be moved
  * new folder. This array must be num_msgs sized.
  *
@@ -557,10 +563,12 @@ int ast_vm_msg_forward(const char *from_mailbox,
 /*!
  * \brief Play a voicemail msg back on a channel.
  *
+ * \param chan
  * \param mailbox msg is in.
  * \param context of mailbox.
- * \param voicemail folder to look in.
- * \param message number in the voicemailbox to playback to the channel.
+ * \param folder voicemail folder to look in.
+ * \param msg_num message number in the voicemailbox to playback to the channel.
+ * \param cb
  *
  * \retval 0 success
  * \retval -1 failure
@@ -643,7 +651,7 @@ int ast_control_streamfile(struct ast_channel *chan, const char *file, const cha
  * \param chan
  * \param file filename
  * \param fwd, rev, stop, pause, restart, skipms, offsetms
- * \param waitstream callback to invoke when fastforward or rewind occurrs.
+ * \param cb waitstream callback to invoke when fastforward or rewind occurrs.
  *
  * Before calling this function, set this to be the number
  * of ms to start from the beginning of the file.  When the function
diff --git a/include/asterisk/bridging_features.h b/include/asterisk/bridging_features.h
index e377ca6b4..e32c183ac 100644
--- a/include/asterisk/bridging_features.h
+++ b/include/asterisk/bridging_features.h
@@ -197,7 +197,7 @@ int ast_bridge_features_unregister(enum ast_bridge_builtin_feature feature);
  * \param dtmf DTMF string to be activated upon
  * \param callback Function to execute upon activation
  * \param hook_pvt Unique data
- * \param Optional destructor callback for hook_pvt data
+ * \param destructor Optional destructor callback for hook_pvt data
  *
  * \retval 0 on success
  * \retval -1 on failure
@@ -226,9 +226,9 @@ int ast_bridge_features_hook(struct ast_bridge_features *features,
 /*! \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.
+ * \param talker_cb Callback function to execute when talking events occur in the bridge core.
  * \param pvt_data Optional unique data that will be passed with the talking events.
- * \param Optional destructor callback for pvt data.
+ * \param talker_destructor Optional destructor callback for pvt data.
  *
  * \retval 0, success
  * \retval -1, failure
diff --git a/include/asterisk/doxygen/architecture.h b/include/asterisk/doxygen/architecture.h
index c157697ee..d507044ee 100644
--- a/include/asterisk/doxygen/architecture.h
+++ b/include/asterisk/doxygen/architecture.h
@@ -26,7 +26,7 @@
 \author Russell Bryant <russell@digium.com>
 \AsteriskTrunkWarning
 
-<hr/>
+<hr>
 
 \section ArchTOC Table of Contents
 
@@ -64,7 +64,7 @@
     -# \ref ArchThreadDebugging
     -# \ref ArchMemoryDebugging
 
-<hr/>
+<hr>
 
 \section ArchIntro Introduction
 
@@ -295,7 +295,7 @@ many events to one call.  The CEL modules look very similar to CDR modules.
 
 CEL modules typically live in the <code>cel/</code> directory in the source tree.
 
-For a list of CEL handlers, see \ref cel_drivers.
+For a list of CEL handlers, see cel_drivers.
 
 For additional information about the CEL API, see
 <code>include/asterisk/cel.h</code>.
@@ -407,7 +407,7 @@ When an inbound channel executes an application such as <code>Dial()</code>, an
 outbound channel is created and bridged to the inbound channel once it answers.
 
 Dialplan applications always execute in the context of a channel thread.  Dialplan
-functions \i almost always do, as well.  However, it is possible to read and write
+functions almost always do, as well.  However, it is possible to read and write
 dialplan functions from an asynchronous interface such as the Asterisk CLI or the
 manager interface (AMI).  However, it is still always the channel thread that is
 the owner of the ast_channel data structure.
@@ -710,7 +710,7 @@ The implementation of this memory debugging system can be found in
 <code>main/astmm.c</code>.
 
 
-<hr/>
+<hr>
 Return to the \ref ArchTOC
  */
 
diff --git a/include/asterisk/doxygen/asterisk-git-howto.h b/include/asterisk/doxygen/asterisk-git-howto.h
index ee35b76f3..3a13792c9 100644
--- a/include/asterisk/doxygen/asterisk-git-howto.h
+++ b/include/asterisk/doxygen/asterisk-git-howto.h
@@ -23,7 +23,7 @@
  *
  * \AsteriskTrunkWarning
  *
- * <hr/>
+ * <hr>
  *
  * \section Introduction Introduction
  * This document will instruct you how to setup a local git mirror of the 
@@ -32,7 +32,7 @@
  * Why would you want that? for starters, it's a fast repository browser
  * and works well even when offline. More on why and why not at 'Pros and Cons'
  * in the end of this document. 
- * <hr/>
+ * <hr>
  *
  * \section Setup Setup
  *
@@ -120,7 +120,7 @@
   echo 'exclude res_snmp' >build_tools/conf
  \endverbatim
  *
- * <hr/>
+ * <hr>
  *
  * \section Update Update
  * The main Asterisk repository tends to get new commits occasionally. I
@@ -133,7 +133,7 @@
  \endverbatim
  *
  * Next, get all updates.
- * <hr/>
+ * <hr>
  *
  * \section Usage Usage
  *
@@ -183,7 +183,7 @@
   git svn rebase --fetch-all
  \endverbatim
  *
- * <hr/>
+ * <hr>
  *
  * \section ProsAndCons Pros and Cons
  *
@@ -233,5 +233,5 @@
  *  to test that. Even if it will, it will require an extra step of manual
  *  editing.
  *
- * <hr/>
+ * <hr>
  */
diff --git a/include/asterisk/doxygen/commits.h b/include/asterisk/doxygen/commits.h
index 33df679d2..7f39c6e8e 100644
--- a/include/asterisk/doxygen/commits.h
+++ b/include/asterisk/doxygen/commits.h
@@ -23,23 +23,23 @@
  *
  * \AsteriskTrunkWarning
  *
- * <hr/>
+ * <hr>
  *
  * \section CommitMsgFormatting Commit Message Formatting
  *
  * The following illustrates the basic outline for commit messages:
  *
-  \verbatim
-  <One-liner summary of changes>
-
-  <Empty Line> 
-
-  <Verbose description of the changes>
-
-  <Empty Line> 
-
-  <Special Tags>
-  \endverbatim
+ * \verbatim
+ * <One-liner summary of changes>
+ *
+ * <Empty Line> 
+ *
+ * <Verbose description of the changes>
+ *
+ * <Empty Line> 
+ *
+ * <Special Tags>
+ * \endverbatim
  *
  * Some commit history viewers treat the first line of commit messages as the
  * summary for the commit.  So, an effort should be made to format our commit
@@ -52,7 +52,7 @@
  * \note For trivial commits, such as "fix the build", or "fix spelling mistake",
  *       the verbose description may not be necessary.
  *
- * <hr/>
+ * <hr>
  *
  * \section CommitMsgTags Special Tags for Commit Messages
  *
@@ -77,12 +77,12 @@
  *
  * Here is an example of what the template will generate for you:
  *
-  \verbatim
-  (closes issue #1234)
-  Reported by: SomeGuy
-  Patches:
-       fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
-  \endverbatim
+ * \verbatim
+ * (closes issue #1234)
+ * Reported by: SomeGuy
+ * Patches:
+ *      fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
+ * \endverbatim
  *
  * If the patch being committed was written by the person doing the commit,
  * and is not available to reference as an upload to the issue, there is no
@@ -97,7 +97,7 @@
  *
  * \note The trailing slash in the review URL is required.
  *
- * <hr/>
+ * <hr>
  *
  * \section CommitMsgSvnmerge Commit Messages with svnmerge
  *
diff --git a/include/asterisk/doxygen/mantisworkflow.h b/include/asterisk/doxygen/mantisworkflow.h
index 3e1755710..cb5f341bf 100644
--- a/include/asterisk/doxygen/mantisworkflow.h
+++ b/include/asterisk/doxygen/mantisworkflow.h
@@ -23,7 +23,7 @@
  *
  * \AsteriskTrunkWarning
  *
- * <hr/>
+ * <hr>
  * \section WorkflowDescription Description of the Issue Tracker Workflow
  * 
  * (This document is most beneficial for Asterisk bug marshals, however it is good
diff --git a/include/asterisk/doxygen/releases.h b/include/asterisk/doxygen/releases.h
index c895d1c3c..7e53f3769 100644
--- a/include/asterisk/doxygen/releases.h
+++ b/include/asterisk/doxygen/releases.h
@@ -133,7 +133,7 @@
  *
  * \arg \ref ReleaseStatus
  *
- * <hr/>
+ * <hr>
  *
  * \section commitmonitoring Commit Monitoring
  *
@@ -141,7 +141,7 @@
  * <a href="http://lists.digium.com/">http://lists.digium.com</a>.  The Digium
  * mailing list server hosts a %number of mailing lists for commits.
  *
- * <hr/>
+ * <hr>
  *
  * \section ast10policy Asterisk 1.0
  *
@@ -154,7 +154,7 @@
  *
  * No commits should be made to the Asterisk 1.0 branch.
  * 
- * <hr/>
+ * <hr>
  *
  * \section ast12policy Asterisk 1.2
  *
@@ -181,7 +181,7 @@
  *  - 1.2.X.Y - a release that contains fixes to the security patches released in
  *    version 1.2.X
  *
- * <hr/>
+ * <hr>
  *
  * \section ast14policy Asterisk 1.4
  *
@@ -208,7 +208,7 @@
  *  - 1.4.X.Y - a release that contains very few changes on top of 1.4.X.  This
  *    may be for a security patch, or for a regression introduced in 1.4.X.
  *
- * <hr/>
+ * <hr>
  *
  * \section ast16policy Asterisk 1.6
  *
@@ -244,7 +244,7 @@
  *  - 1.6.X.Y - a release that contains fixes for bugs or security issues identified
  *    in the 1.6.X release series.
  *
- * <hr/>
+ * <hr>
  *
  * \section asttrunk Asterisk Trunk
  *
@@ -269,7 +269,7 @@
  * tested and reviewed such that there is reasonable belief that the code
  * is ready to go.
  *
- * <hr/>
+ * <hr>
  *
  * \section astteam Asterisk Team Branches
  *
diff --git a/include/asterisk/doxygen/reviewboard.h b/include/asterisk/doxygen/reviewboard.h
index b86445416..0b05b01dd 100644
--- a/include/asterisk/doxygen/reviewboard.h
+++ b/include/asterisk/doxygen/reviewboard.h
@@ -23,7 +23,7 @@
  *
  * \AsteriskTrunkWarning
  *
- * <hr/>
+ * <hr>
  *
  * \section ReviewboardGuidelines Usage Guidelines
  *
@@ -52,7 +52,7 @@
  * testing and should not have blatant coding guidelines violations.  Lack of
  * these things is careless and shows disrespect for those reviewing your code.
  *
- * <hr/>
+ * <hr>
  *
  * \section ReviewboardPosting Posting Code to Reviewboard
  *
@@ -61,25 +61,25 @@
  * The easiest way to post a patch to reviewboard is by using the
  * post-review tool.  We have post-review in our repotools svn repository.
  *
-   \verbatim
-   $ svn co http://svn.digium.com/svn/repotools
-   \endverbatim
+ * \verbatim
+ * $ svn co http://svn.digium.com/svn/repotools
+ * \endverbatim
  *
  * Essentially, post-review is a script that will take the output of "svn
  * diff" and create a review request out of it for you.  So, once you have
  * a working copy with the changes you expect in the output of "svn diff",
  * you just run the following command:
  *
-   \verbatim
-   $ post-review
-   \endverbatim
+ * \verbatim
+ * $ post-review
+ * \endverbatim
  * 
  * If it complains about not knowing which reviewboard server to use, add
  * the server option:
  * 
-   \verbatim
-   $ post-review --server=https://reviewboard.asterisk.org
-   \endverbatim
+ * \verbatim
+ * $ post-review --server=https://reviewboard.asterisk.org
+ * \endverbatim
  *
  * \subsection postreviewnewfiles Dealing with New Files
  * 
@@ -90,15 +90,15 @@
  * 
  * You would start by getting your changes applied to a trunk working copy:
  * 
-   \verbatim
-   $ cd .../trunk
-   \endverbatim
+ * \verbatim
+ * $ cd .../trunk
+ * \endverbatim
  * 
  * Then, apply the changes from your branch:
  * 
-   \verbatim
-   $ svn merge .../trunk .../team/group/my_new_code
-   \endverbatim
+ * \verbatim
+ * $ svn merge .../trunk .../team/group/my_new_code
+ * \endverbatim
  * 
  * Now, the code is merged into your working copy.  However, for a new
  * file, subversion treats it as a copy of existing content and not new
@@ -106,10 +106,10 @@
  * it to show up in the diff, use the following commands so svn treats it
  * as new content and publishes it in the diff:
  * 
-   \verbatim
-   $ svn revert my_new_file.c
-   $ svn add my_new_file.c
-   \endverbatim
+ * \verbatim
+ * $ svn revert my_new_file.c
+ * $ svn add my_new_file.c
+ * \endverbatim
  * 
  * Now, it should work, and you can run "post-review" as usual.
  *
@@ -121,7 +121,7 @@
  * Apply the current version of the diff to a working copy as described above,
  * and then run the following command:
  * 
-   \verbatim
-   $ post-review -r <review request number>
-   \endverbatim
+ * \verbatim
+ * $ post-review -r <review request number>
+ * \endverbatim
  */
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 096901cd2..b61714311 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -68,7 +68,7 @@
  * \arg \b Main:  Asterisk Developer's website http://www.asterisk.org/developers/
  * \arg \b Bugs: The Issue Tracker https://issues.asterisk.org
  * \arg \b Lists: List Server http://lists.digium.com
- * \arg \b Wiki: The Asterisk Wiki 	http://www.voip-info.org
+ * \arg \b Wiki: The Asterisk Wiki 	http://wiki.asterisk..org
  * \arg \b Docs: The Asterisk Documentation Project http://www.asteriskdocs.org
  * \arg \b Digium: The Asterisk Company http://www.digium.com
  */
@@ -92,8 +92,6 @@
  * \arg \ref AstExtState
  * \arg \ref AstDataRetrieval
  *
- * \subsection model_txt Generic Model
- * \verbinclude model.txt
  * \subsection channel_txt Channels
  * \arg See \ref Def_Channel
  */
@@ -224,7 +222,6 @@
  * - \ref pbx_retrieve_variable()
  * - \ref AstChanVar
  *
- *  \verbinclude channelvariables.tex
  */
 
 /*! 
@@ -281,7 +278,6 @@
  * \arg \ref enum.c
  * \arg \ref func_enum.c
  *
- * \verbinclude enum.txt
  */
 
 /*! 
@@ -334,7 +330,6 @@
 
 /*! 
  * \page Config_ast Asterisk.conf
- * \verbinclude asterisk-conf.txt
  */
 
 /*! 
@@ -373,11 +368,9 @@
  * IAX2 is implemented in \ref chan_iax2.c
  * \arg \link Config_iax iax.conf Configuration file example \endlink
  * \section iaxreadme IAX readme file
- * \verbinclude iax.txt
  * \section Config_iax IAX Configuration example
  * \verbinclude iax.conf.sample
  * \section iaxjitter IAX Jitterbuffer information
- * \verbinclude jitterbuffer.txt
  */
 
 /*! 
@@ -409,7 +402,6 @@
  * \page README_misdn MISDN documentation
  * \arg See \ref Config_misdn
  * \section mISDN configuration
- * \verbinclude misdn.txt
  */
 
 /*! 
@@ -728,7 +720,6 @@
  * \arg Configuration file:
  * \verbinclude res_config_sqlite.conf
  * \arg SQL tables:
- * \verbinclude res_config_sqlite.txt
  * \arg See also:
  * http://www.sqlite.org
  */
diff --git a/include/asterisk/jabber.h b/include/asterisk/jabber.h
index 8c627466c..63d3292e0 100644
--- a/include/asterisk/jabber.h
+++ b/include/asterisk/jabber.h
@@ -21,7 +21,7 @@
  * \arg \ref AJI_intro
  * \ref res_jabber.c
  * \author Matt O'Gorman <mogorman@digium.com>
- * \extref IKSEMEL http://iksemel.jabberstudio.org
+ * IKSEMEL http://iksemel.jabberstudio.org
  *
  * \page AJI_intro AJI - The Asterisk Jabber Interface
  * 
diff --git a/include/asterisk/localtime.h b/include/asterisk/localtime.h
index 5da28dfba..50f5c835c 100644
--- a/include/asterisk/localtime.h
+++ b/include/asterisk/localtime.h
@@ -75,7 +75,6 @@ const char *ast_setlocale(const char *locale);
  * \param len Size of the chunk of memory buf.
  * \param format A string specifying the format of time to be placed into buf.
  * \param tm Pointer to the broken out time to be used for the format.
- * \param locale Text string specifying the locale to be used for language strings.
  * \retval An integer value specifying the number of bytes placed into buf or -1 on error.
  */
 int ast_strftime(char *buf, size_t len, const char *format, const struct ast_tm *tm);
@@ -87,7 +86,6 @@ int ast_strftime_locale(char *buf, size_t len, const char *format, const struct
  * \param s A string specifying some portion of a date and time.
  * \param format The format in which the string, s, is expected.
  * \param tm The broken-out time structure into which the parsed data is expected.
- * \param locale Text string specifying the locale to be used for language strings.
  * \retval A pointer to the first character within s not used to parse the date and time.
  */
 char *ast_strptime(const char *s, const char *format, struct ast_tm *tm);
diff --git a/include/asterisk/res_odbc.h b/include/asterisk/res_odbc.h
index 76d57f74c..7d9d4a19e 100644
--- a/include/asterisk/res_odbc.h
+++ b/include/asterisk/res_odbc.h
@@ -104,9 +104,11 @@ int ast_odbc_smart_execute(struct odbc_obj *obj, SQLHSTMT stmt) __attribute__((d
  * \brief Retrieves a connected ODBC object
  * \param name The name of the ODBC class for which a connection is needed.
  * \param flags One or more of the following flags:
- * \li RES_ODBC_SANITY_CHECK Whether to ensure that a connection is valid before returning the handle.  Usually unnecessary.
- * \li RES_ODBC_INDEPENDENT_CONNECTION Return a handle which is independent from all others.  Usually used when starting a transaction.
- * \li RES_ODBC_CONNECTED Only return a connected handle.  Intended for use with peers which use idlecheck, which are checked periodically for reachability.
+ *	\li RES_ODBC_SANITY_CHECK Whether to ensure that a connection is valid before returning the handle.  Usually unnecessary.
+ *	\li RES_ODBC_INDEPENDENT_CONNECTION Return a handle which is independent from all others.  Usually used when starting a transaction.
+ *	\li RES_ODBC_CONNECTED Only return a connected handle.  Intended for use with peers which use idlecheck, which are checked periodically for reachability.
+ * \param  file, function, lineno
+ *
  * \return ODBC object
  * \retval NULL if there is no connection available with the requested name.
  *
diff --git a/include/asterisk/sip_api.h b/include/asterisk/sip_api.h
index 018785a8d..392456758 100644
--- a/include/asterisk/sip_api.h
+++ b/include/asterisk/sip_api.h
@@ -29,9 +29,10 @@ extern "C" {
 /*!
  * \brief Send a customized SIP INFO request
  *
+ * \param chan Channel
  * \param headers The headers to add to the INFO request
  * \param content_type The content type header to add
- * \param conten The body of the INFO request
+ * \param content The body of the INFO request
  * \param useragent_filter If non-NULL, only send the INFO if the
  * recipient's User-Agent contains useragent_filter as a substring
  *
diff --git a/include/asterisk/xmpp.h b/include/asterisk/xmpp.h
index d0c25707f..644221637 100644
--- a/include/asterisk/xmpp.h
+++ b/include/asterisk/xmpp.h
@@ -19,7 +19,7 @@
 /*! \file
  * \brief XMPP Interface
  * \author Joshua Colp <jcolp@digium.com>
- * \extref IKSEMEL http://iksemel.jabberstudio.org
+ * IKSEMEL http://iksemel.jabberstudio.org
  */
 
 #ifndef _ASTERISK_XMPP_H