Add some clarifying documentation to the ast_str_set and ast_str_append functions.

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

diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 0e904ac..cb522ae 100644 (file)
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -342,11 +342,16 @@ 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)
  *
  *     ast_str_set_va(&buf, max_len, ap)
  *     ast_str_append_va(&buf, max_len, ap)
  *

- * \param max_len The maximum allowed length, reallocating if needed.
+ * \param max_len The maximum allowed capacity of the ast_str. Note that
+ *  if the value of max_len is less than the current capacity of the
+ *  ast_str (as returned by ast_str_size), then the parameter is effectively
+ *  ignored.

  *     0 means unlimited, -1 means "at most the available space"
  *
  * \return All the functions return <0 in case of error, or the
  *     0 means unlimited, -1 means "at most the available space"
  *
  * \return All the functions return <0 in case of error, or the

- *     length of the string added to the buffer otherwise.
+ *     length of the string added to the buffer otherwise. Note that
+ *     in most cases where an error is returned, characters ARE written
+ *     to the ast_str.

  */
 
 /*! \brief The descriptor of a dynamic string
  */
 
 /*! \brief The descriptor of a dynamic string