From eefda8158e44b51bc9d039ba57d06df78cf6e2d8 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 00:44:20 +0100 Subject: [PATCH] docs: Move the GIOStream SECTION Move the contents to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/giostream.c | 63 ++++++++++++++++++++++++------------------------- gio/giostream.h | 5 ---- 2 files changed, 31 insertions(+), 37 deletions(-) diff --git a/gio/giostream.c b/gio/giostream.c index 194ba4998..ec0006f46 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. + * `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. + * 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 */ diff --git a/gio/giostream.h b/gio/giostream.h index 52881c786..f8a958b25 100644 --- a/gio/giostream.h +++ b/gio/giostream.h @@ -40,11 +40,6 @@ G_BEGIN_DECLS typedef struct _GIOStreamPrivate GIOStreamPrivate; typedef struct _GIOStreamClass GIOStreamClass; -/** - * GIOStream: - * - * Base class for read-write streams. - **/ struct _GIOStream { GObject parent_instance;