Fix a bunch of places where \arg was used instead of \param. Using \arg

to document arguments seems logical, and does work, but is not the best
thing to use.

\arg in doxygen is simply for creating non-nested unordered lists.  \param is
the correct tag to use to document function parameters, and will come out
better in the generated documentation.


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@127401 f38db490-d61c-443f-a65b-d21fe96a405b

9 files changed, 61 insertions, 66 deletions

diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
index 5f9776004..ddf29c7e1 100644
--- a/include/asterisk/astobj2.h
+++ b/include/asterisk/astobj2.h
@@ -708,8 +708,8 @@ void *_ao2_link(struct ao2_container *c, void *newobj);
 /*!
  * \brief Remove an object from the container
  *
- * \arg c the container
- * \arg obj the object to unlink
+ * \param c the container
+ * \param obj the object to unlink
  *
  * \retval NULL, always
  *
diff --git a/include/asterisk/devicestate.h b/include/asterisk/devicestate.h
index 69470a9f7..50e43ce14 100644
--- a/include/asterisk/devicestate.h
+++ b/include/asterisk/devicestate.h
@@ -204,7 +204,7 @@ struct ast_devstate_aggregate;
 /*!
  * \brief Initialize aggregate device state
  *
- * \arg agg the state object
+ * \param agg the state object
  *
  * \return nothing
  */
@@ -213,8 +213,8 @@ void ast_devstate_aggregate_init(struct ast_devstate_aggregate *agg);
 /*!
  * \brief Add a device state to the aggregate device state
  *
- * \arg agg the state object
- * \arg state the state to add
+ * \param agg the state object
+ * \param state the state to add
  *
  * \return nothing
  */
@@ -223,7 +223,7 @@ void ast_devstate_aggregate_add(struct ast_devstate_aggregate *agg, enum ast_dev
 /*!
  * \brief Get the aggregate device state result
  *
- * \arg agg the state object
+ * \param agg the state object
  *
  * \return the aggregate device state after adding some number of device states.
  */
diff --git a/include/asterisk/dnsmgr.h b/include/asterisk/dnsmgr.h
index 2738201f5..36011c227 100644
--- a/include/asterisk/dnsmgr.h
+++ b/include/asterisk/dnsmgr.h
@@ -40,8 +40,8 @@ struct ast_dnsmgr_entry;
 /*!
  * \brief Allocate a new DNS manager entry
  *
- * \arg name the hostname
- * \arg result where the DNS manager should store the IP address as it refreshes it.
+ * \param name the hostname
+ * \param result where the DNS manager should store the IP address as it refreshes it.
  *      it.
  *
  * This function allocates a new DNS manager entry object, and fills it with the
@@ -56,7 +56,7 @@ struct ast_dnsmgr_entry *ast_dnsmgr_get(const char *name, struct sockaddr_in *re
 /*!
  * \brief Free a DNS manager entry
  *
- * \arg entry the DNS manager entry to free
+ * \param entry the DNS manager entry to free
  *
  * \return nothing
  */
@@ -65,9 +65,9 @@ void ast_dnsmgr_release(struct ast_dnsmgr_entry *entry);
 /*!
  * \brief Allocate and initialize a DNS manager entry
  *
- * \arg name the hostname
- * \arg result where to store the IP address as the DNS manager refreshes it
- * \arg dnsmgr Where to store the allocate DNS manager entry
+ * \param name the hostname
+ * \param result where to store the IP address as the DNS manager refreshes it
+ * \param dnsmgr Where to store the allocate DNS manager entry
  *
  * This function allocates a new DNS manager entry object, and fills it with
  * the provided hostname and IP address.  This function _does_ force an initial
diff --git a/include/asterisk/logger.h b/include/asterisk/logger.h
index 45407e81d..7d03d8894 100644
--- a/include/asterisk/logger.h
+++ b/include/asterisk/logger.h
@@ -183,14 +183,14 @@ void ast_console_toggle_loglevel(int fd, int leve, int state);
 
 /*!
  * \brief Get the debug level for a file
- * \arg file the filename
+ * \param file the filename
  * \return the debug level
  */
 unsigned int ast_debug_get_by_file(const char *file);
 
 /*!
  * \brief Get the debug level for a file
- * \arg file the filename
+ * \param file the filename
  * \return the debug level
  */
 unsigned int ast_verbose_get_by_file(const char *file);
diff --git a/include/asterisk/slinfactory.h b/include/asterisk/slinfactory.h
index 4d3e8eaf8..1b13b5a24 100644
--- a/include/asterisk/slinfactory.h
+++ b/include/asterisk/slinfactory.h
@@ -43,7 +43,7 @@ struct ast_slinfactory {
 /*!
  * \brief Initialize an slinfactory
  *
- * \arg sf The slinfactory to initialize
+ * \param sf The slinfactory to initialize
  *
  * \return Nothing
  */
@@ -52,7 +52,7 @@ void ast_slinfactory_init(struct ast_slinfactory *sf);
 /*!
  * \brief Destroy the contents of a slinfactory
  *
- * \arg sf The slinfactory that is no longer needed
+ * \param sf The slinfactory that is no longer needed
  *
  * This function will free any memory allocated for the contents of the
  * slinfactory.  It does not free the slinfactory itself.  If the sf is
@@ -65,8 +65,8 @@ void ast_slinfactory_destroy(struct ast_slinfactory *sf);
 /*!
  * \brief Feed audio into an slinfactory
  *
- * \arg sf The slinfactory to feed into
- * \arg f Frame containing audio to feed in
+ * \param sf The slinfactory to feed into
+ * \param f Frame containing audio to feed in
  *
  * \return Number of frames currently in factory
  */
@@ -75,9 +75,9 @@ int ast_slinfactory_feed(struct ast_slinfactory *sf, struct ast_frame *f);
 /*!
  * \brief Read samples from an slinfactory
  *
- * \arg sf The slinfactory to read from
- * \arg buf Buffer to put samples into
- * \arg samples Number of samples wanted
+ * \param sf The slinfactory to read from
+ * \param buf Buffer to put samples into
+ * \param samples Number of samples wanted
  *
  * \return Number of samples read
  */
@@ -86,7 +86,7 @@ int ast_slinfactory_read(struct ast_slinfactory *sf, short *buf, size_t samples)
 /*!
  * \brief Retrieve number of samples currently in an slinfactory
  *
- * \arg sf The slinfactory to peek into
+ * \param sf The slinfactory to peek into
  *
  * \return Number of samples in slinfactory
  */
@@ -95,7 +95,7 @@ unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf);
 /*!
  * \brief Flush the contents of an slinfactory
  *
- * \arg sf The slinfactory to flush
+ * \param sf The slinfactory to flush
  *
  * \return Nothing
  */
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 79dac8700..13d68d3fc 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -62,8 +62,7 @@ static force_inline int ast_strlen_zero(const char *s)
 
 /*!
   \brief Gets a pointer to the first non-whitespace character in a string.
-  \param ast_skip_blanks function being used
-  \arg str the input string
+  \param str the input string
   \return a pointer to the first non-whitespace character
  */
 AST_INLINE_API(
@@ -77,8 +76,7 @@ char *ast_skip_blanks(const char *str),
 
 /*!
   \brief Trims trailing whitespace characters from a string.
-  \param ast_skip_blanks function being used
-  \arg str the input string
+  \param str the input string
   \return a pointer to the modified string
  */
 AST_INLINE_API(
@@ -103,8 +101,7 @@ char *ast_trim_blanks(char *str),
 
 /*!
   \brief Gets a pointer to first whitespace character in a string.
-  \param ast_skip_noblanks function being used
-  \arg str the input string
+  \param str the input string
   \return a pointer to the first whitespace character
  */
 AST_INLINE_API(
@@ -118,8 +115,7 @@ char *ast_skip_nonblanks(char *str),
   
 /*!
   \brief Strip leading/trailing whitespace from a string.
-  \param ast_strip function ast_strip being used.
-  \arg s The string to be stripped (will be modified).
+  \param s The string to be stripped (will be modified).
   \return The stripped string.
 
   This functions strips all leading and trailing whitespace
@@ -178,9 +174,9 @@ char *ast_unescape_c(char *s);
 
 /*!
   \brief Size-limited null-terminating string copy.
-  \arg dst The destination buffer.
-  \arg src The source string
-  \arg size The size of the destination buffer
+  \param dst The destination buffer.
+  \param src The source string
+  \param size The size of the destination buffer
   \return Nothing.
 
   This is similar to \a strncpy, with two important differences:
@@ -213,9 +209,9 @@ void ast_copy_string(char *dst, const char *src, size_t size),
   This is a wrapper for snprintf, that properly handles the buffer pointer
   and buffer space available.
 
-  \arg buffer current position in buffer to place string into (will be updated on return)
-  \arg space remaining space in buffer (will be updated on return)
-  \arg fmt printf-style format string
+  \param buffer current position in buffer to place string into (will be updated on return)
+  \param space remaining space in buffer (will be updated on return)
+  \param fmt printf-style format string
   \retval 0 on success
   \retval non-zero on failure.
 */
@@ -325,7 +321,7 @@ int ast_get_timeval(const char *src, struct timeval *tv, struct timeval _default
  *	ast_str_set_va(&buf, max_len, ap)
  *	ast_str_append_va(&buf, max_len, ap)
  *
- * \arg max_len The maximum allowed length, reallocating if needed.
+ * \param max_len The maximum allowed length, reallocating if needed.
  * 	0 means unlimited, -1 means "at most the available space"
  *
  * \return All the functions return <0 in case of error, or the
@@ -352,7 +348,7 @@ struct ast_str {
 /*!
  * \brief Create a malloc'ed dynamic length string
  *
- * \arg init_len This is the initial length of the string buffer
+ * \param init_len This is the initial length of the string buffer
  *
  * \return This function returns a pointer to the dynamic string length.  The
  *         result will be NULL in the case of a memory allocation error.
@@ -444,11 +440,11 @@ int ast_str_make_space(struct ast_str **buf, size_t new_len),
 /*!
  * \brief Retrieve a thread locally stored dynamic string
  *
- * \arg ts This is a pointer to the thread storage structure declared by using
+ * \param ts This is a pointer to the thread storage structure declared by using
  *      the AST_THREADSTORAGE macro.  If declared with 
  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
  *      (&my_buf).
- * \arg init_len This is the initial length of the thread's dynamic string. The
+ * \param init_len This is the initial length of the thread's dynamic string. The
  *      current length may be bigger if previous operations in this thread have
  *      caused it to increase.
  *
@@ -540,15 +536,15 @@ enum {
 /*!
  * \brief Set a dynamic string from a va_list
  *
- * \arg buf This is the address of a pointer to a struct ast_str.
+ * \param buf This is the address of a pointer to a struct ast_str.
  *	If it is retrieved using ast_str_thread_get, the
 	struct ast_threadstorage pointer will need to
  *      be updated in the case that the buffer has to be reallocated to
  *      accommodate a longer string than what it currently has space for.
- * \arg max_len This is the maximum length to allow the string buffer to grow
+ * \param max_len This is the maximum length to allow the string buffer to grow
  *      to.  If this is set to 0, then there is no maximum length.
- * \arg fmt This is the format string (printf style)
- * \arg ap This is the va_list
+ * \param fmt This is the format string (printf style)
+ * \param ap This is the va_list
  *
  * \return The return value of this function is the same as that of the printf
  *         family of functions.
@@ -634,14 +630,14 @@ int __ast_str_helper(struct ast_str **buf, size_t max_len,
 /*!
  * \brief Set a dynamic string using variable arguments
  *
- * \arg buf This is the address of a pointer to a struct ast_str which should
+ * \param buf This is the address of a pointer to a struct ast_str which should
  *      have been retrieved using ast_str_thread_get.  It will need to
  *      be updated in the case that the buffer has to be reallocated to
  *      accomodate a longer string than what it currently has space for.
- * \arg max_len This is the maximum length to allow the string buffer to grow
+ * \param max_len This is the maximum length to allow the string buffer to grow
  *      to.  If this is set to 0, then there is no maximum length.
  *	If set to -1, we are bound to the current maximum length.
- * \arg fmt This is the format string (printf style)
+ * \param fmt This is the format string (printf style)
  *
  * \return The return value of this function is the same as that of the printf
  *         family of functions.
diff --git a/include/asterisk/threadstorage.h b/include/asterisk/threadstorage.h
index 5e6b3c348..77f9428b7 100644
--- a/include/asterisk/threadstorage.h
+++ b/include/asterisk/threadstorage.h
@@ -75,7 +75,7 @@ void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len
 /*!
  * \brief Define a thread storage variable
  *
- * \arg name The name of the thread storage object
+ * \param name The name of the thread storage object
  *
  * This macro would be used to declare an instance of thread storage in a file.
  *
@@ -90,11 +90,11 @@ void __ast_threadstorage_object_replace(void *key_old, void *key_new, size_t len
 /*!
  * \brief Define a thread storage variable, with custom initialization and cleanup
  *
- * \arg name The name of the thread storage object
- * \arg init This is a custom function that will be called after each thread specific
+ * \param name The name of the thread storage object
+ * \param init This is a custom function that will be called after each thread specific
  *           object is allocated, with the allocated block of memory passed
  *           as the argument.
- * \arg cleanup This is a custom function that will be called instead of ast_free
+ * \param cleanup This is a custom function that will be called instead of ast_free
  *              when the thread goes away.  Note that if this is used, it *MUST*
  *              call free on the allocated memory.
  *
@@ -137,11 +137,11 @@ static void __init_##name(void)					\
 /*!
  * \brief Retrieve thread storage
  *
- * \arg ts This is a pointer to the thread storage structure declared by using
+ * \param ts This is a pointer to the thread storage structure declared by using
  *      the AST_THREADSTORAGE macro.  If declared with 
  *      AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be 
  *      (&my_buf).
- * \arg init_size This is the amount of space to be allocated the first time
+ * \param init_size This is the amount of space to be allocated the first time
  *      this thread requests its data. Thus, this should be the size that the
  *      code accessing this thread storage is assuming the size to be.
  *
diff --git a/include/asterisk/time.h b/include/asterisk/time.h
index 8abce667d..4b7ca00ff 100644
--- a/include/asterisk/time.h
+++ b/include/asterisk/time.h
@@ -57,9 +57,8 @@ int ast_tvdiff_sec(struct timeval end, struct timeval start),
 
 /*!
  * \brief Computes the difference (in microseconds) between two \c struct \c timeval instances.
- * \param ast_tvdiff_sec 
- * \arg end the end of the time period
- * \arg start the beginning of the time period
+ * \param end the end of the time period
+ * \param start the beginning of the time period
  * \return the difference in microseconds
  */
 AST_INLINE_API(
diff --git a/include/asterisk/timing.h b/include/asterisk/timing.h
index 88f1fc17d..659eb7229 100644
--- a/include/asterisk/timing.h
+++ b/include/asterisk/timing.h
@@ -107,7 +107,7 @@ int ast_timer_open(void);
 /*!
  * \brief Close an opened timing handle
  *
- * \arg handle timing fd returned from timer_open()
+ * \param handle timing fd returned from timer_open()
  *
  * \return nothing
  */
@@ -116,8 +116,8 @@ void ast_timer_close(int handle);
 /*!
  * \brief Set the timing tick rate
  *
- * \arg handle timing fd returned from timer_open()
- * \arg rate ticks per second, 0 turns the ticks off if needed
+ * \param handle timing fd returned from timer_open()
+ * \param rate ticks per second, 0 turns the ticks off if needed
  *
  * Use this function if you want the timing fd to show input at a certain
  * rate.  The other alternative use of a timing fd, is using the continuous
@@ -131,8 +131,8 @@ int ast_timer_set_rate(int handle, unsigned int rate);
 /*!
  * \brief Acknowledge a timer event
  *
- * \arg handle timing fd returned from timer_open()
- * \arg quantity number of timer events to acknowledge
+ * \param handle timing fd returned from timer_open()
+ * \param quantity number of timer events to acknowledge
  *
  * \note This function should only be called if timer_get_event()
  *       returned AST_TIMING_EVENT_EXPIRED.
@@ -144,7 +144,7 @@ void ast_timer_ack(int handle, unsigned int quantity);
 /*!
  * \brief Enable continuous mode
  *
- * \arg handle timing fd returned from timer_open()
+ * \param handle timing fd returned from timer_open()
  *
  * Continuous mode causes poll() on the timing fd to immediately return
  * always until continuous mode is disabled.
@@ -157,7 +157,7 @@ int ast_timer_enable_continuous(int handle);
 /*!
  * \brief Disable continuous mode
  *
- * \arg handle timing fd returned from timer_close()
+ * \param handle timing fd returned from timer_close()
  *
  * \retval -1 failure, with errno set
  * \retval 0 success
@@ -167,7 +167,7 @@ int ast_timer_disable_continuous(int handle);
 /*!
  * \brief Determine timing event
  *
- * \arg handle timing fd returned by timer_open()
+ * \param handle timing fd returned by timer_open()
  *
  * After poll() indicates that there is input on the timing fd, this will
  * be called to find out what triggered it.
@@ -179,7 +179,7 @@ enum ast_timing_event ast_timer_get_event(int handle);
 /*!
  * \brief Get maximum rate supported for a timing handle
  *
- * \arg handle timing fd returned by timer_open()
+ * \param handle timing fd returned by timer_open()
  *
  * \return maximum rate supported for timing handle
  */