[glib] gsocketconnection: Document closing connections with g_io_stream_close()

[Philip Withnall <pwithnall src gnome org>]

commit 169846c5ab19abaa5474f5b5f30c3deef645ee03
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Feb 13 10:58:21 2014 +0000

    gsocketconnection: Document closing connections with g_io_stream_close()
    
    It’s not enough to close a connection by calling g_input_stream_close()
    and g_output_stream_close() on its two substreams: to close the
    underlying socket, one must use g_io_stream_close(). Document that.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=724278

 gio/giostream.c         |    6 +++---
 gio/gsocketconnection.c |    4 ++++
 2 files changed, 7 insertions(+), 3 deletions(-)
---
diff --git a/gio/giostream.c b/gio/giostream.c
index a93a822..34b07fc 100644
--- a/gio/giostream.c
+++ b/gio/giostream.c
@@ -55,9 +55,9 @@
  * To close a stream use g_io_stream_close() which will close the common
  * stream object and also the individual substreams. You can also close
  * the substreams themselves. In most cases this only marks the
- * substream as closed, so further I/O on it fails. However, some streams
- * may support "half-closed" states where one direction of the stream
- * is actually shut down.
+ * substream as closed, so further I/O on it fails but common state in the
+ * #GIOStream may still be open. However, some streams may support
+ * "half-closed" states where one direction of the stream is actually shut down.
  *
  * Since: 2.22
  */
diff --git a/gio/gsocketconnection.c b/gio/gsocketconnection.c
index 50e50ba..9f490c8 100644
--- a/gio/gsocketconnection.c
+++ b/gio/gsocketconnection.c
@@ -56,6 +56,10 @@
  * custom socket connection types for specific combination of socket
  * family/type/protocol using g_socket_connection_factory_register_type().
  *
+ * To close a #GSocketConnection, use g_io_stream_close(). Closing both
+ * substreams of the #GIOStream separately will not close the underlying
+ * #GSocket.
+ *
  * Since: 2.22
  */