Fix a bunch of places where \arg was used instead of \param. Using \arg
authorRussell Bryant <russell@russellbryant.com>
Wed, 2 Jul 2008 14:50:45 +0000 (14:50 +0000)
committerRussell Bryant <russell@russellbryant.com>
Wed, 2 Jul 2008 14:50:45 +0000 (14:50 +0000)
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: https://origsvn.digium.com/svn/asterisk/trunk@127401 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/astobj2.h
include/asterisk/devicestate.h
include/asterisk/dnsmgr.h
include/asterisk/logger.h
include/asterisk/slinfactory.h
include/asterisk/strings.h
include/asterisk/threadstorage.h
include/asterisk/time.h
include/asterisk/timing.h
main/libresample/include/libresample.h

index 5f97760..ddf29c7 100644 (file)
@@ -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
  *
index 69470a9..50e43ce 100644 (file)
@@ -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.
  */
index 2738201..36011c2 100644 (file)
@@ -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
index 45407e8..7d03d88 100644 (file)
@@ -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);
index 4d3e8ea..1b13b5a 100644 (file)
@@ -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
  */
index 79dac87..13d68d3 100644 (file)
@@ -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.
index 5e6b3c3..77f9428 100644 (file)
@@ -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.
  *
index 8abce66..4b7ca00 100644 (file)
@@ -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(
index 88f1fc1..659eb72 100644 (file)
@@ -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
  */
index e5ce485..43ccab5 100644 (file)
@@ -27,12 +27,12 @@ extern "C" {
 /*!
  * \brief Create a resampler
  *
- * \arg highQuality Set this argument to non-zero to enable higher quality
+ * \param highQuality Set this argument to non-zero to enable higher quality
  *      resampling.  
- * \arg minFactor This is the minimum resampling factor that will be used for
+ * \param minFactor This is the minimum resampling factor that will be used for
  *      this resampler.  The resampling factor is calculated in the following
  *      way: ( from sample rate / to sample rate ).
- * \arg maxFactor This is the maximum resampling factor that will be used for
+ * \param maxFactor This is the maximum resampling factor that will be used for
  *      this resampler.
  *
  * Use this function to create a new resampler that will maintain state
@@ -47,7 +47,7 @@ void *resample_open(int      highQuality,
 /*!
  * \brief Duplicate a resampler
  *
- * \arg handle the resampler to duplicate
+ * \param handle the resampler to duplicate
  *
  * \return A new handle to a resampler, initialized with the same parameters
  * used to create the original resampler.
@@ -57,7 +57,7 @@ void *resample_dup(const void *handle);
 /*!
  * \brief Get filter width for resampler
  * 
- * \arg handle the resampler
+ * \param handle the resampler
  *
  * \return the filter width.
  */
@@ -66,22 +66,22 @@ int resample_get_filter_width(const void *handle);
 /*!
  * \brief Resample a chunk of audio
  *
- * \arg handle the resampler
- * \arg factor the resampling factor.  This factor should be calculated as
+ * \param handle the resampler
+ * \param factor the resampling factor.  This factor should be calculated as
  *      ( from sample rate / to sample rate ).  So, for converting from 8 kHz
  *      to 16 kHz, this value would be 2.0.
- * \arg inBuffer the input buffer for audio to resample.
- * \arg inBufferLen the number of samples in the input buffer
- * \arg lastFlag Set this argument to non-zero if the data in the input buffer
+ * \param inBuffer the input buffer for audio to resample.
+ * \param inBufferLen the number of samples in the input buffer
+ * \param lastFlag Set this argument to non-zero if the data in the input buffer
  *      is known to be the end of a stream.  This would be used if you're
  *      resampling a file, for example.
- * \arg inBufferUsed This is an output parameter that indicates how many
+ * \param inBufferUsed This is an output parameter that indicates how many
  *      samples were consumed from the input buffer.  Generally, this function
  *      is called in a loop until you know that the entire input buffer has
  *      been consumed, as it may take multiple calls to complete.
- * \arg outBuffer This is the output buffer.  This function will write the
+ * \param outBuffer This is the output buffer.  This function will write the
  *      resampled audio into this buffer.
- * \arg outBufferLen This parameter specifies how many samples there is room
+ * \param outBufferLen This parameter specifies how many samples there is room
  *      for in the output buffer.
  *
  * This is the main function used for resampling audio.  It should be called
@@ -104,7 +104,7 @@ int resample_process(void   *handle,
 /*!
  * \brief Close a resampler
  *
- * \arg handle the resampler to close
+ * \param handle the resampler to close
  * 
  * Use this function to release a handle to a resampler that was created using
  * either resample_open() or resample_dup().