Update librsync.h docs about processing directly from large input buffers.

This points out that large buffers can be processed directly and can leave a
tail of data behind in the input buffer. Using large buffers avoids data
copies and can be much faster.

1 files changed, 11 insertions, 5 deletions

diff --git a/src/librsync.h b/src/librsync.h
index 83fb27d..fec8fed 100644
--- a/src/librsync.h
+++ b/src/librsync.h
@@ -312,11 +312,17 @@ LIBRSYNC_EXPORT void rs_sumset_dump(rs_signature_t const *);
  * entry, and suitable to be passed in on a second call, but they don't
  * directly tell you how much output data was produced.
  *
- * Note also that if *#avail_in is nonzero on return, then not all of the input
- * data has been consumed. The caller should either provide more output buffer
- * space and call ::rs_job_iter() again passing the same #next_in and
- * #avail_in, or put the remaining input data into some persistent buffer and
- * call rs_job_iter() with it again when there is more output space.
+ * If the input buffer was large enough, it will be processed directly,
+ * otherwise the data can be copied and accumulated into an internal buffer for
+ * processing. This means using larger buffers can be much more efficient.
+ *
+ * Note also that if #avail_in is nonzero on return, then not all of the input
+ * data has been consumed. This can happen either because it ran out of output
+ * buffer space, or because it processed as much data as possible directly from
+ * the input buffer and needs more input to proceed without copying into
+ * internal buffers. The caller should provide more output buffer space and/or
+ * pack the remaining input data into another buffer with more input before
+ * calling rs_job_iter() again.
  *
  * \sa rs_job_iter() */
 struct rs_buffers_s {