[glib] glib: Slightly update GIOChannel documentation

[Philip Withnall <pwithnall src gnome org>]

commit f813ce6abe89c2d26f5b8c8e5f41d24923a525e9
Author: Bastien Nocera <hadess hadess net>
Date:   Fri Sep 1 14:53:21 2017 +0200

    glib: Slightly update GIOChannel documentation
    
    Explain the default values of _{get,set}_close_on_unref() in the main
    description rather than the argument one, link to the GIOChannel
    structure when talking about it, and mention the default value of
    "close on unref" in g_io_channel_unix_new().
    
    https://bugzilla.gnome.org/show_bug.cgi?id=787123

 glib/giochannel.c |   13 +++++++------
 glib/giounix.c    |    2 ++
 2 files changed, 9 insertions(+), 6 deletions(-)
---
diff --git a/glib/giochannel.c b/glib/giochannel.c
index bdbaa5e..fa90ea2 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -1012,12 +1012,14 @@ g_io_channel_get_flags (GIOChannel *channel)
  * g_io_channel_set_close_on_unref:
  * @channel: a #GIOChannel
  * @do_close: Whether to close the channel on the final unref of
- *            the GIOChannel data structure. The default value of
- *            this is %TRUE for channels created by g_io_channel_new_file (),
- *            and %FALSE for all other channels.
+ *            the GIOChannel data structure.
+ *
+ * Whether to close the channel on the final unref of the #GIOChannel
+ * data structure. The default value of this is %TRUE for channels
+ * created by g_io_channel_new_file (), and %FALSE for all other channels.
  *
  * Setting this flag to %TRUE for a channel you have already closed
- * can cause problems.
+ * can cause problems when the final reference to the #GIOChannel is dropped.
  **/
 void
 g_io_channel_set_close_on_unref        (GIOChannel *channel,
@@ -1037,8 +1039,7 @@ g_io_channel_set_close_on_unref   (GIOChannel *channel,
  * destroyed. The default value of this is %TRUE for channels created
  * by g_io_channel_new_file (), and %FALSE for all other channels.
  *
- * Returns: Whether the channel will be closed on the final unref of
- *               the GIOChannel data structure.
+ * Returns: %TRUE if the channel will be closed, %FALSE otherwise.
  **/
 gboolean
 g_io_channel_get_close_on_unref        (GIOChannel *channel)
diff --git a/glib/giounix.c b/glib/giounix.c
index af80a2c..b368aff 100644
--- a/glib/giounix.c
+++ b/glib/giounix.c
@@ -592,6 +592,8 @@ g_io_channel_new_file (const gchar *filename,
  * is reading output from a command using via pipe, you may need to set
  * the encoding to the encoding of the current locale (see
  * g_get_charset()) with the g_io_channel_set_encoding() function.
+ * By default, the fd passed will not be closed when the final reference
+ * to the #GIOChannel data structure is dropped.
  *
  * If you want to read raw binary data without interpretation, then
  * call the g_io_channel_set_encoding() function with %NULL for the