[glib] docs: explain inconsistency of _{read,write}_all()

[Ryan Lortie <desrt src gnome org>]

commit 223b5f757fe07cdec2879315965297a31edc3478
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Sep 29 11:50:05 2014 -0400

    docs: explain inconsistency of _{read,write}_all()
    
    These functions are inconsistent with our normal conventions in that
    they set an output variable to a specified value, even in the case that
    an error is thrown.
    
    Document very clearly that this should be considered exceptional.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=737451

 gio/ginputstream.c  |   10 ++++++++--
 gio/goutputstream.c |   11 +++++++++--
 2 files changed, 17 insertions(+), 4 deletions(-)
---
diff --git a/gio/ginputstream.c b/gio/ginputstream.c
index ab8ceb4..a1ba736 100644
--- a/gio/ginputstream.c
+++ b/gio/ginputstream.c
@@ -223,8 +223,14 @@ g_input_stream_read  (GInputStream  *stream,
  * read into @buffer.
  * 
  * If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_read is updated to contain
- * the number of bytes read into @buffer before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered.  This functionality is only
+ * available from C.  If you need it from another language then you must
+ * write your own loop around g_input_stream_read().
  *
  * Returns: %TRUE on success, %FALSE if there was an error
  **/
diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index dc15ff8..2bec89e 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -246,8 +246,15 @@ g_output_stream_write (GOutputStream  *stream,
  * is set to @count.
  * 
  * If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_written is updated to contain
- * the number of bytes written into the stream before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered.  This
+ * functionality is only available from C.  If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write().
  *
  * Returns: %TRUE on success, %FALSE if there was an error
  **/