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

@@ -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
  */

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
  */