[asterisk-commits] russell: trunk r127401 - in /trunk: include/asterisk/ main/libresample/include/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Wed Jul 2 09:50:46 CDT 2008
Author: russell
Date: Wed Jul 2 09:50:45 2008
New Revision: 127401
URL: http://svn.digium.com/view/asterisk?view=rev&rev=127401
Log:
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.
Modified:
trunk/include/asterisk/astobj2.h
trunk/include/asterisk/devicestate.h
trunk/include/asterisk/dnsmgr.h
trunk/include/asterisk/logger.h
trunk/include/asterisk/slinfactory.h
trunk/include/asterisk/strings.h
trunk/include/asterisk/threadstorage.h
trunk/include/asterisk/time.h
trunk/include/asterisk/timing.h
trunk/main/libresample/include/libresample.h
Modified: trunk/include/asterisk/astobj2.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/astobj2.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/astobj2.h (original)
+++ trunk/include/asterisk/astobj2.h Wed Jul 2 09:50:45 2008
@@ -708,8 +708,8 @@
/*!
* \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
*
Modified: trunk/include/asterisk/devicestate.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/devicestate.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/devicestate.h (original)
+++ trunk/include/asterisk/devicestate.h Wed Jul 2 09:50:45 2008
@@ -204,7 +204,7 @@
/*!
* \brief Initialize aggregate device state
*
- * \arg agg the state object
+ * \param agg the state object
*
* \return nothing
*/
@@ -213,8 +213,8 @@
/*!
* \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 @@
/*!
* \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.
*/
Modified: trunk/include/asterisk/dnsmgr.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/dnsmgr.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/dnsmgr.h (original)
+++ trunk/include/asterisk/dnsmgr.h Wed Jul 2 09:50:45 2008
@@ -40,8 +40,8 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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
Modified: trunk/include/asterisk/logger.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/logger.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/logger.h (original)
+++ trunk/include/asterisk/logger.h Wed Jul 2 09:50:45 2008
@@ -183,14 +183,14 @@
/*!
* \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);
Modified: trunk/include/asterisk/slinfactory.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/slinfactory.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/slinfactory.h (original)
+++ trunk/include/asterisk/slinfactory.h Wed Jul 2 09:50:45 2008
@@ -43,7 +43,7 @@
/*!
* \brief Initialize an slinfactory
*
- * \arg sf The slinfactory to initialize
+ * \param sf The slinfactory to initialize
*
* \return Nothing
*/
@@ -52,7 +52,7 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \brief Flush the contents of an slinfactory
*
- * \arg sf The slinfactory to flush
+ * \param sf The slinfactory to flush
*
* \return Nothing
*/
Modified: trunk/include/asterisk/strings.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/strings.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/strings.h (original)
+++ trunk/include/asterisk/strings.h Wed Jul 2 09:50:45 2008
@@ -62,8 +62,7 @@
/*!
\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 @@
/*!
\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 @@
/*!
\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 @@
/*!
\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 @@
/*!
\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 @@
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 @@
* 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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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.
Modified: trunk/include/asterisk/threadstorage.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/threadstorage.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/threadstorage.h (original)
+++ trunk/include/asterisk/threadstorage.h Wed Jul 2 09:50:45 2008
@@ -75,7 +75,7 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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.
*
Modified: trunk/include/asterisk/time.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/time.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/time.h (original)
+++ trunk/include/asterisk/time.h Wed Jul 2 09:50:45 2008
@@ -57,9 +57,8 @@
/*!
* \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(
Modified: trunk/include/asterisk/timing.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/timing.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/include/asterisk/timing.h (original)
+++ trunk/include/asterisk/timing.h Wed Jul 2 09:50:45 2008
@@ -107,7 +107,7 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \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
*/
Modified: trunk/main/libresample/include/libresample.h
URL: http://svn.digium.com/view/asterisk/trunk/main/libresample/include/libresample.h?view=diff&rev=127401&r1=127400&r2=127401
==============================================================================
--- trunk/main/libresample/include/libresample.h (original)
+++ trunk/main/libresample/include/libresample.h Wed Jul 2 09:50:45 2008
@@ -27,12 +27,12 @@
/*!
* \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 @@
/*!
* \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 @@
/*!
* \brief Get filter width for resampler
*
- * \arg handle the resampler
+ * \param handle the resampler
*
* \return the filter width.
*/
@@ -66,22 +66,22 @@
/*!
* \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 @@
/*!
* \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().
More information about the asterisk-commits
mailing list