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

10 files changed, 45 insertions, 26 deletions

diff --git a/main/acl.c b/main/acl.c
index 3c2810753..236d8b6c4 100644
--- a/main/acl.c
+++ b/main/acl.c
@@ -371,7 +371,7 @@ struct ast_acl_list *ast_duplicate_acl_list(struct ast_acl_list *original)
  * \param netmask The netmask configured in the host access rule.
  * \param result The resultant address after applying the netmask to the given address
  * \retval 0 Successfully applied netmask
- * \reval -1 Failed to apply netmask
+ * \retval -1 Failed to apply netmask
  */
 static int apply_netmask(const struct ast_sockaddr *addr, const struct ast_sockaddr *netmask,
 		struct ast_sockaddr *result)
diff --git a/main/ast_expr2f.c b/main/ast_expr2f.c
index 622f0334c..1f67d460d 100644
--- a/main/ast_expr2f.c
+++ b/main/ast_expr2f.c
@@ -2142,8 +2142,8 @@ void ast_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
- * @param yyscanner The scanner object.
+ * \param column_no line_number
+ * \param yyscanner The scanner object.
  */
 void ast_yyset_column (int  column_no , yyscan_t yyscanner)
 {
diff --git a/main/asterisk.c b/main/asterisk.c
index e8b9b34de..ff3775194 100644
--- a/main/asterisk.c
+++ b/main/asterisk.c
@@ -21,6 +21,15 @@
 /*!
  * \mainpage Asterisk -- The Open Source Telephony Project
  *
+ * \par Welcome
+ *
+ * This documentation created by the Doxygen project clearly explains the
+ * internals of the Asterisk software. This documentation contains basic
+ * examples, developer documentation, support information, and information
+ * for upgrading.
+ * 
+ * 
+ * 
  * \par Developer Documentation for Asterisk
  *
  * This is the main developer documentation for Asterisk. It is
@@ -44,19 +53,19 @@
  * of <a href="http://www.digium.com">Digium, Inc</a>.
  *
  * \author Mark Spencer <markster@digium.com>
- * Also see \ref AstCREDITS
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
  * any of the maintainers of this project for assistance;
  * the project provides a web site, mailing lists, and IRC
  * channels for your use.
+ *
+ * \todo Add pages for mailinglists, IRC, etc...
  */
 
 /*! \file
-  \brief Top level source file for Asterisk  - the Open Source PBX. Implementation
-  of PBX core functions and CLI interface.
-
+ * \brief Top level source file for Asterisk - the Open Source PBX.
+ *	Implementation of PBX core functions and CLI interface.
  */
 
 /*** MODULEINFO
@@ -1024,7 +1033,8 @@ static struct sigaction ignore_sig_handler = {
 
 AST_MUTEX_DEFINE_STATIC(safe_system_lock);
 /*! \brief Keep track of how many threads are currently trying to wait*() on
- *  a child process */
+ *  a child process
+ */
 static unsigned int safe_system_level = 0;
 static struct sigaction safe_system_prev_handler;
 
@@ -1200,7 +1210,7 @@ static void ast_network_puts(const char *string)
 }
 
 /*!
- * write the string to the console, and all attached
+ * \brief write the string to the console, and all attached
  * console clients
  */
 void ast_console_puts(const char *string)
@@ -1537,10 +1547,10 @@ static int ast_tryconnect(void)
 }
 
 /*! \brief Urgent handler
-
- Called by soft_hangup to interrupt the poll, read, or other
- system call.  We don't actually need to do anything though.
- Remember: Cannot EVER ast_log from within a signal handler
+ *
+ * Called by soft_hangup to interrupt the poll, read, or other
+ * system call.  We don't actually need to do anything though.
+ * Remember: Cannot EVER ast_log from within a signal handler
  */
 static void _urg_handler(int num)
 {
@@ -1628,8 +1638,10 @@ static void set_icon(char *text)
 		fprintf(stdout, "\033]1;%s\007", text);
 }
 
-/*! \brief We set ourselves to a high priority, that we might pre-empt everything
-   else.  If your PBX has heavy activity on it, this is a good thing.  */
+/*! \brief We set ourselves to a high priority, that we might pre-empt
+ * everything else.  If your PBX has heavy activity on it, this is a
+ * good thing.
+ */
 int ast_set_priority(int pri)
 {
 	struct sched_param sched;
@@ -1737,7 +1749,8 @@ static int can_safely_quit(shutdown_nice_t niceness, int restart)
 	}
 
 	/* Re-acquire lock and check if someone changed the niceness, in which
-	 * case someone else has taken over the shutdown. */
+	 * case someone else has taken over the shutdown.
+	 */
 	ast_mutex_lock(&safe_system_lock);
 	if (shuttingdown != niceness) {
 		if (shuttingdown == NOT_SHUTTING_DOWN && option_verbose && ast_opt_console) {
@@ -3478,7 +3491,10 @@ int main(int argc, char *argv[])
 
 	if (getenv("HOME"))
 		snprintf(filename, sizeof(filename), "%s/.asterisk_history", getenv("HOME"));
-	/* Check for options */
+	/*! \brief Check for options
+	 *
+	 * \todo Document these options
+	 */
 	while ((c = getopt(argc, argv, "BC:cde:FfG:ghIiL:M:mnpqRrs:TtU:VvWXx:")) != -1) {
 		/*!\note Please keep the ordering here to alphabetical, capital letters
 		 * first.  This will make it easier in the future to select unused
diff --git a/main/ccss.c b/main/ccss.c
index 76b02dac6..2480c7d38 100644
--- a/main/ccss.c
+++ b/main/ccss.c
@@ -568,6 +568,8 @@ static enum ast_device_state cc_state_to_devstate_map[] = {
  * \intenral
  * \brief lookup the ast_device_state mapped to cc_state
  *
+ * \param state
+ *
  * \return the correponding DEVICE STATE from the cc_state_to_devstate_map
  * when passed an internal state.
  */
@@ -1638,7 +1640,7 @@ struct extension_child_dialstring {
 	 *
 	 * \details
 	 * This serves mainly as a key when searching for a particular dialstring.
-	 * For instance, let's say that we have called device SIP/400@somepeer. This
+	 * For instance, let's say that we have called device SIP/400\@somepeer. This
 	 * device offers call completion, but then due to some unforeseen circumstance,
 	 * this device backs out and makes CC unavailable. When that happens, we need
 	 * to find the dialstring that corresponds to that device, and we use the
diff --git a/main/http.c b/main/http.c
index 55ade21d7..de8a57388 100644
--- a/main/http.c
+++ b/main/http.c
@@ -25,7 +25,7 @@
  * This program implements a tiny http server
  * and was inspired by micro-httpd by Jef Poskanzer
  *
- * \extref GMime http://spruce.sourceforge.net/gmime/
+ * GMime http://spruce.sourceforge.net/gmime/
  *
  * \ref AstHTTP - AMI over the http protocol
  */
diff --git a/main/manager.c b/main/manager.c
index 19c7b67ff..bb55544ab 100644
--- a/main/manager.c
+++ b/main/manager.c
@@ -22,7 +22,7 @@
  *
  * \author Mark Spencer <markster@digium.com>
  *
- * \extref OpenSSL http://www.openssl.org - for AMI/SSL
+ * OpenSSL http://www.openssl.org - for AMI/SSL
  *
  * At the moment this file contains a number of functions, namely:
  *
diff --git a/main/sha1.c b/main/sha1.c
index 41ec2f025..97bd2dd87 100644
--- a/main/sha1.c
+++ b/main/sha1.c
@@ -336,7 +336,7 @@ static void SHA1ProcessMessageBlock(SHA1Context *context)
 /*!
  * \brief This helper function finishes off the digest calculations.
  * \param context [in/out]  The context to pad.
- * \param Pad_byte [in]  The last byte to add to the message block
+ * \param Pad_Byte [in]  The last byte to add to the message block
  *     before the 0-padding and length.  This will contain the last
  *     bits of the message followed by another single bit.  If the
  *     message was an exact multiple of 8-bits long, Pad_Byte will
@@ -359,7 +359,7 @@ static void SHA1Finalize(SHA1Context * context, uint8_t Pad_Byte)
 /*!
  * \brief Pad message to be 512 bits.
  * \param context [in/out]  The context to pad.
- * \param Pad_byte [in]  Last padding byte.
+ * \param Pad_Byte [in]  Last padding byte.
  *
  *  According to the standard, the message must be padded to the next
  *  even multiple of 512 bits.  The first padding bit must be a '1'.
diff --git a/main/strings.c b/main/strings.c
index 285ec9287..47715e63e 100644
--- a/main/strings.c
+++ b/main/strings.c
@@ -70,7 +70,7 @@ int __ast_str_helper(struct ast_str **buf, ssize_t max_len,
 		}
 		/*
 		 * Ask vsnprintf how much space we need. Remember that vsnprintf
-		 * does not count the final <code>'\0'</code> so we must add 1.
+		 * does not count the final <code>'\\0'</code> so we must add 1.
 		 */
 		va_copy(aq, ap);
 		res = vsnprintf((*buf)->__AST_STR_STR + offset, (*buf)->__AST_STR_LEN - offset, fmt, aq);
diff --git a/main/tdd.c b/main/tdd.c
index 2a8b8693f..a590e3b2f 100644
--- a/main/tdd.c
+++ b/main/tdd.c
@@ -281,8 +281,9 @@ static inline float tdd_getcarrier(float *cr, float *ci, int bit)
 } while(0);
 
 /*! Generate TDD hold tone
- * \param buf Result buffer
- * \todo How big should this be??? */
+ * \param outbuf, buf Result buffer
+ * \todo How big should this be?
+ */
 int tdd_gen_holdtone(unsigned char *buf)
 {
 	int bytes = 0;
diff --git a/main/xmldoc.c b/main/xmldoc.c
index 0dc56c4b3..c06b3ba8a 100644
--- a/main/xmldoc.c
+++ b/main/xmldoc.c
@@ -20,7 +20,7 @@
  *
  * \author Eliel C. Sardanons (LU1ALY) <eliels@gmail.com>
  *
- * \extref libxml2 http://www.xmlsoft.org/
+ * libxml2 http://www.xmlsoft.org/
  */
 
 /*** MODULEINFO