Imported Upstream version 2.79.0upstream/2.79.0

1 files changed, 57 insertions, 42 deletions

diff --git a/gio/giostream.c b/gio/giostream.c
index 194ba4998..d9398fef1 100644
--- a/gio/giostream.c
+++ b/gio/giostream.c
@@ -32,57 +32,56 @@
 #include "gtask.h"
 
 /**
- * SECTION:giostream
- * @short_description: Base class for implementing read/write streams
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
+ * GIOStream:
  *
- * GIOStream represents an object that has both read and write streams.
+ * `GIOStream` represents an object that has both read and write streams.
  * Generally the two streams act as separate input and output streams,
  * but they share some common resources and state. For instance, for
  * seekable streams, both streams may use the same position.
  *
- * Examples of #GIOStream objects are #GSocketConnection, which represents
- * a two-way network connection; and #GFileIOStream, which represents a
+ * Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents
+ * a two-way network connection; and [class@Gio.FileIOStream], which represents a
  * file handle opened in read-write mode.
  *
  * To do the actual reading and writing you need to get the substreams
- * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
+ * with [method@Gio.IOStream.get_input_stream] and
+ * [method@Gio.IOStream.get_output_stream].
  *
- * The #GIOStream object owns the input and the output streams, not the other
- * way around, so keeping the substreams alive will not keep the #GIOStream
- * object alive. If the #GIOStream object is freed it will be closed, thus
+ * The `GIOStream` object owns the input and the output streams, not the other
+ * way around, so keeping the substreams alive will not keep the `GIOStream`
+ * object alive. If the `GIOStream` object is freed it will be closed, thus
  * closing the substreams, so even if the substreams stay alive they will
- * always return %G_IO_ERROR_CLOSED for all operations.
+ * always return `G_IO_ERROR_CLOSED` for all operations.
  *
- * To close a stream use g_io_stream_close() which will close the common
+ * To close a stream use [method@Gio.IOStream.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 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.
- *
- * Operations on #GIOStreams cannot be started while another operation on the
- * #GIOStream or its substreams is in progress. Specifically, an application can
- * read from the #GInputStream and write to the #GOutputStream simultaneously
- * (either in separate threads, or as asynchronous operations in the same
- * thread), but an application cannot start any #GIOStream operation while there
- * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
- * an application can’t start any #GInputStream or #GOutputStream operation
- * while there is a #GIOStream operation in progress.
+ * `GIOStream` may still be open. However, some streams may support
+ * ‘half-closed’ states where one direction of the stream is actually shut down.
+ *
+ * Operations on `GIOStream`s cannot be started while another operation on the
+ * `GIOStream` or its substreams is in progress. Specifically, an application can
+ * read from the [class@Gio.InputStream] and write to the
+ * [class@Gio.OutputStream] simultaneously (either in separate threads, or as
+ * asynchronous operations in the same thread), but an application cannot start
+ * any `GIOStream` operation while there is a `GIOStream`, `GInputStream` or
+ * `GOutputStream` operation in progress, and an application can’t start any
+ * `GInputStream` or `GOutputStream` operation while there is a `GIOStream`
+ * operation in progress.
  *
  * This is a product of individual stream operations being associated with a
- * given #GMainContext (the thread-default context at the time the operation was
- * started), rather than entire streams being associated with a single
- * #GMainContext.
+ * given [type@GLib.MainContext] (the thread-default context at the time the
+ * operation was started), rather than entire streams being associated with a
+ * single `GMainContext`.
  *
- * GIO may run operations on #GIOStreams from other (worker) threads, and this
+ * GIO may run operations on `GIOStream`s from other (worker) threads, and this
  * may be exposed to application code in the behaviour of wrapper streams, such
- * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
- * application code may only run operations on the base (wrapped) stream when
- * the wrapper stream is idle. Note that the semantics of such operations may
- * not be well-defined due to the state the wrapper stream leaves the base
- * stream in (though they are guaranteed not to crash).
+ * as [class@Gio.BufferedInputStream] or [class@Gio.TlsConnection]. With such
+ * wrapper APIs, application code may only run operations on the base (wrapped)
+ * stream when the wrapper stream is idle. Note that the semantics of such
+ * operations may not be well-defined due to the state the wrapper stream leaves
+ * the base stream in (though they are guaranteed not to crash).
  *
  * Since: 2.22
  */
@@ -172,23 +171,39 @@ g_io_stream_class_init (GIOStreamClass *klass)
   klass->close_async = g_io_stream_real_close_async;
   klass->close_finish = g_io_stream_real_close_finish;
 
+  /**
+   * GIOStream:closed:
+   *
+   * Whether the stream is closed.
+   *
+   * Since: 2.22
+   */
   g_object_class_install_property (gobject_class, PROP_CLOSED,
-                                   g_param_spec_boolean ("closed",
-                                                         P_("Closed"),
-                                                         P_("Is the stream closed"),
+                                   g_param_spec_boolean ("closed", NULL, NULL,
                                                          FALSE,
                                                          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+  /**
+   * GIOStream:input-stream:
+   *
+   * The [class@Gio.InputStream] to read from.
+   *
+   * Since: 2.22
+   */
   g_object_class_install_property (gobject_class, PROP_INPUT_STREAM,
-				   g_param_spec_object ("input-stream",
-							P_("Input stream"),
-							P_("The GInputStream to read from"),
+				   g_param_spec_object ("input-stream", NULL, NULL,
 							G_TYPE_INPUT_STREAM,
 							G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+  /**
+   * GIOStream:output-stream:
+   *
+   * The [class@Gio.OutputStream] to write to.
+   *
+   * Since: 2.22
+   */
   g_object_class_install_property (gobject_class, PROP_OUTPUT_STREAM,
-				   g_param_spec_object ("output-stream",
-							P_("Output stream"),
-							P_("The GOutputStream to write to"),
+				   g_param_spec_object ("output-stream", NULL, NULL,
 							G_TYPE_OUTPUT_STREAM,
 							G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 }