[glib] outputstream: Clarify docs of flush()

[Benjamin Otte <otte src gnome org>]

commit 482f226270efd6c0c8d336b9146376986979e1f4
Author: Benjamin Otte <otte redhat com>
Date:   Mon Dec 5 22:40:18 2011 +0100

    outputstream: Clarify docs of flush()
    
    After questioning the semantics of flush on IRC, it seemed necessary to
    clarify what flushing is supposed to do. The Linux man page for fflush()
    seemed to cover it perfectly, so I just copied it.
    
    I did not add the "via the underlying write mechanism" part as that in
    my opinion is not something subclasses should need to guarantee.

 gio/goutputstream.c |    8 +++++---
 1 files changed, 5 insertions(+), 3 deletions(-)
---
diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index afe135c..9f3493d 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -296,8 +296,9 @@ g_output_stream_write_all (GOutputStream  *stream,
  * @cancellable: (allow-none): optional cancellable object
  * @error: location to store the error occurring, or %NULL to ignore
  *
- * Flushed any outstanding buffers in the stream. Will block during 
- * the operation. Closing the stream will implicitly cause a flush.
+ * Forces a write of all user-space buffered data for the given
+ * @stream. Will block during the operation. Closing the stream will
+ * implicitly cause a flush.
  *
  * This function is optional for inherited classes.
  * 
@@ -939,7 +940,8 @@ g_output_stream_splice_finish (GOutputStream  *stream,
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: (closure): the data to pass to callback function
  * 
- * Flushes a stream asynchronously.
+ * Forces an asynchronous write of all user-space buffered data for
+ * the given @stream.
  * For behaviour details see g_output_stream_flush().
  *
  * When the operation is finished @callback will be