[asterisk-commits] mmichelson: branch 1.6.1 r246987 - in /branches/1.6.1: ./ include/asterisk/

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Tue Feb 16 15:17:06 2010
New Revision: 246987

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=246987
Log:
Merged revisions 246985 via svnmerge from 
https://origsvn.digium.com/svn/asterisk/trunk

........
  r246985 | mmichelson | 2010-02-16 15:15:38 -0600 (Tue, 16 Feb 2010) | 3 lines
  
  Add some clarifying documentation to the ast_str_set and ast_str_append functions.
........

Modified:
    branches/1.6.1/   (props changed)
    branches/1.6.1/include/asterisk/strings.h

Propchange: branches/1.6.1/
------------------------------------------------------------------------------
Binary property 'trunk-merged' - no diff available.

Modified: branches/1.6.1/include/asterisk/strings.h
URL: http://svnview.digium.com/svn/asterisk/branches/1.6.1/include/asterisk/strings.h?view=diff&rev=246987&r1=246986&r2=246987
==============================================================================
--- branches/1.6.1/include/asterisk/strings.h (original)
+++ branches/1.6.1/include/asterisk/strings.h Tue Feb 16 15:17:06 2010
@@ -323,11 +323,16 @@
  *	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
- *	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