svn commit: r1575252 - /subversion/trunk/subversion/include/svn_delta.h

[ju...@apache.org]

Author: julianfoad
Date: Fri Mar  7 13:05:08 2014
New Revision: 1575252

URL: http://svn.apache.org/r1575252
Log:
* subversion/include/svn_delta.h
  (svn_txdelta_parse_svndiff): Write a more substantial doc string.

Modified:
    subversion/trunk/subversion/include/svn_delta.h

Modified: subversion/trunk/subversion/include/svn_delta.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_delta.h?rev=1575252&r1=1575251&r2=1575252&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_delta.h (original)
+++ subversion/trunk/subversion/include/svn_delta.h Fri Mar  7 13:05:08 2014
@@ -545,10 +545,26 @@ svn_txdelta_to_svndiff(svn_stream_t *out
 
 /** Return a writable generic stream which will parse svndiff-format
  * data into a text delta, invoking @a handler with @a handler_baton
- * whenever a new window is ready.  If @a error_on_early_close is @c
- * TRUE, attempting to close this stream before it has handled the entire
- * svndiff data set will result in #SVN_ERR_SVNDIFF_UNEXPECTED_END,
- * else this error condition will be ignored.
+ * whenever a new window is ready.
+ *
+ * When the caller closes this stream, this will signal completion to
+ * the window handler by invoking @a handler once more, passing zero for
+ * the @c window argument.
+ *
+ * If @a error_on_early_close is @c TRUE, then attempt to avoid
+ * signaling completion to the window handler if the delta was
+ * incomplete. Specifically, attempting to close the stream will be
+ * successful only if the data written to the stream consisted of one or
+ * more complete windows of svndiff data and no extra bytes. Otherwise,
+ * closing the stream will not signal completion to the window handler,
+ * and will return a #SVN_ERR_SVNDIFF_UNEXPECTED_END error. Note that if
+ * no data at all was written, the delta is considered incomplete.
+ *
+ * If @a error_on_early_close is @c FALSE, closing the stream will
+ * signal completion to the window handler, regardless of how much data
+ * was written, and discard any pending incomplete data.
+ *
+ * Allocate the stream in @a pool.
  */
 svn_stream_t *
 svn_txdelta_parse_svndiff(svn_txdelta_window_handler_t handler,