- Fix a few spelling mistakes.

- Add some more documentation for the ast_dynamic_str_............() function
  to document the behavior of the function in the case of a partial write.
  Also, document the return value and note that the function should never need
  to be called directly.


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

1 files changed, 19 insertions, 4 deletions

diff --git a/include/asterisk/threadstorage.h b/include/asterisk/threadstorage.h
index 25bc24b71..f03e264b2 100644
--- a/include/asterisk/threadstorage.h
+++ b/include/asterisk/threadstorage.h
@@ -205,7 +205,7 @@ struct ast_dynamic_str * attribute_malloc ast_dynamic_str_create(size_t init_len
  *      current length may be bigger if previous operations in this thread have
  *      caused it to increase.
  *
- * \return This function will return the thread locally storaged dynamic string
+ * \return This function will return the thread locally stored dynamic string
  *         associated with the thread storage management variable passed as the
  *         first argument.
  *         The result will be NULL in the case of a memory allocation error.
@@ -261,7 +261,7 @@ enum {
  * \arg buf This is the address of a pointer to an ast_dynamic_str which should
  *      have been retrieved using ast_dynamic_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.
+ *      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
  *      to.  If this is set to 0, then there is no maximum length.
  * \arg ts This is a pointer to the thread storage structure declared by using
@@ -332,6 +332,21 @@ enum {
  * ast_dynamic_str_thread_set_va except for an addition argument, append.
  * If append is non-zero, this will append to the current string instead of
  * writing over it.
+ *
+ * In the case that this function is called and the buffer was not large enough
+ * to hold the result, the partial write will be truncated, and the result
+ * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size
+ * was increased, and the function should be called a second time.
+ *
+ * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error.
+ *
+ * A return value greater than or equal to zero indicates the number of
+ * characters that have been written, not including the terminating '\0'.
+ * In the append case, this only includes the number of characters appended.
+ *
+ * \note This function should never need to be called directly.  It should
+ *       through calling one of the other functions or macros defined in this
+ *       file.
  */
 int ast_dynamic_str_thread_build_va(struct ast_dynamic_str **buf, size_t max_len,
 	struct ast_threadstorage *ts, int append, const char *fmt, va_list ap);
@@ -419,7 +434,7 @@ int __attribute__ ((format (printf, 4, 5))) ast_dynamic_str_thread_append(
  *
  * \arg buf This is the address of a pointer to an ast_dynamic_str.  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.
+ *      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
  *      to.  If this is set to 0, then there is no maximum length.
  *
@@ -443,7 +458,7 @@ int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_set(
 )
 
 /*!
- * \brief Append to a dynatic string
+ * \brief Append to a dynamic string
  *
  * The arguments, return values, and usage of this function are the same as
  * ast_dynamic_str_set().  However, this function appends to the string instead