--- a/render_remote.h	Thu Jun 05 22:53:47 2008 +0300
+++ b/render_remote.h	Thu Jun 05 23:04:28 2008 +0300
@@ -22,7 +22,7 @@
  *
  * cb_sent will be invoked after the request has succesfully been written, and before cb_data is called.
  * cb_data is called whenever new data has been received. See also, render_remote_set_chunk_size
- * cb_done is called when all the data has been passed to cb_data
+ * cb_done is called after our last call to cb_data (note: see render_remote_shake)
  * cb_fail is called when an error is encountered. This can (and will) happen at any time!
  */
 struct remote_render_ctx *render_remote (
@@ -36,22 +36,28 @@
 );
 
 /*
- * Cancel the given request. No more callbacks will be called, buffered data is discarded and the remote render process will cancel asap.
+ * Cancel the given request. No more callbacks will be called, buffered data is
+ * discarded and the remote render process will cancel ASAP.
  */
 void render_remote_cancel (struct remote_render_ctx *ctx);
 
 /*
  * Controls the behaviour of when cb_data is called, and how remote data is read in.
  *
- * recv_threshold, sets a threshold for calling cb_data - cb_data will only be called
- * if the buffer contains at least recv_threshold, bytes. Note that cb_data is only
- * ever called when new data has been receieved from the remote end - never
- * otherwise. If cb_data doesn't drain the buffer, cb_data will be called again
- * once more data has been received from the remote end.
+ * recv_threshold sets a threshold for calling cb_data - cb_data will only be
+ * called if the buffer contains at least recv_threshold bytes. Note that
+ * cb_data is only called once new data has been receieved from the remote end.
+ * If cb_data doesn't drain the buffer, cb_data will be called again once more
+ * data has been received from the remote end.
  *
- * overflow_size can be used to control the amount of unread data in cb_data. If 
- * the buffer contains more than recv_threshold + unread_buffer bytes, we will stop
- * accepting bytes from the remote end, and cb_data will not be called any more.
+ * unread_buffer can be used to control the amount of unread data in cb_data.
+ * If the buffer contains more than recv_threshold + unread_buffer bytes, we
+ * will stop accepting bytes from the remote end, and cb_data will not be
+ * called any more.
+ *
+ * This means that there is a potential for deadlock if the buffer is full. You
+ * MUST call render_remote_shake once you are ready to start consuming the
+ * buffer again.
  *
  * Only call this once cb_sent has fired
  */