[libvirt] [PATCH libvirt-glib 0/3] Doc updates
Hi, here are some doc updates I found on a long unused branch but they still apply. Cheers, -- Guido Guido Günther (3): Add some missing docs streams: fix references gvir_stream_send: make it obvious that we send bytes libvirt-gobject/libvirt-gobject-connection.c | 15 ++++++++++- libvirt-gobject/libvirt-gobject-domain.c | 2 +- libvirt-gobject/libvirt-gobject-stream.c | 38 ++++++++++++++++++---------- 3 files changed, 39 insertions(+), 16 deletions(-) -- 2.14.1
--- libvirt-gobject/libvirt-gobject-connection.c | 15 ++++++++++++++- libvirt-gobject/libvirt-gobject-domain.c | 2 +- libvirt-gobject/libvirt-gobject-stream.c | 10 ++++++++++ 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/libvirt-gobject/libvirt-gobject-connection.c b/libvirt-gobject/libvirt-gobject-connection.c index 3f17265..47a3f0c 100644 --- a/libvirt-gobject/libvirt-gobject-connection.c +++ b/libvirt-gobject/libvirt-gobject-connection.c @@ -487,6 +487,10 @@ static gboolean _gvir_connection_open(GVirConnection *conn, * gvir_connection_open: * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object + * + * Open a connection + * + * Returns: TRUE on success, FALSE on error */ gboolean gvir_connection_open(GVirConnection *conn, GCancellable *cancellable, @@ -495,6 +499,15 @@ gboolean gvir_connection_open(GVirConnection *conn, return _gvir_connection_open(conn, FALSE, cancellable, err); } +/** + * gvir_connection_open_read_only: + * @conn: a #GVirConnection + * @cancellable: (allow-none)(transfer none): cancellation object + * + * Open a connection read only + * + * Returns: TRUE on success, FALSE on error + */ gboolean gvir_connection_open_read_only(GVirConnection *conn, GCancellable *cancellable, GError **err) @@ -1340,7 +1353,7 @@ G_DEFINE_BOXED_TYPE(GVirConnectionHandle, gvir_connection_handle, * @conn: a #GVirConnection * @flags: flags to use for the stream * - * Return value: (transfer full): a #GVirStream stream, or NULL.The returned + * Return value: (transfer full): a #GVirStream stream, or NULL. The returned * object should be unreffed with g_object_unref() when no longer needed. */ GVirStream *gvir_connection_get_stream(GVirConnection *self, diff --git a/libvirt-gobject/libvirt-gobject-domain.c b/libvirt-gobject/libvirt-gobject-domain.c index 7be936d..3bfc65f 100644 --- a/libvirt-gobject/libvirt-gobject-domain.c +++ b/libvirt-gobject/libvirt-gobject-domain.c @@ -1088,8 +1088,8 @@ end: /** * gvir_domain_open_console: * @dom: (transfer none): the domain - * @devname: (transfer none)(allow-none): the device name * @stream: (transfer none): stream to use as output + * @devname: (transfer none)(allow-none): the device name * @flags: extra flags, currently unused * * Open a text console for the domain @dom, connecting it to the diff --git a/libvirt-gobject/libvirt-gobject-stream.c b/libvirt-gobject/libvirt-gobject-stream.c index a518a19..b6bf774 100644 --- a/libvirt-gobject/libvirt-gobject-stream.c +++ b/libvirt-gobject/libvirt-gobject-stream.c @@ -67,6 +67,16 @@ enum { }; +/** + * SECTION:gvir-stream + * @short_description: Streaming operations for domain input and output + * + * #GVirStream implements #GInputStream and #GOutputStream for reading from and + * writing to a domain e.g. via a text based console on a emulated serial port. + * + * It is usually created via #gvir_connection_get_stream. + */ + #define GVIR_STREAM_ERROR gvir_stream_error_quark() static void gvir_stream_update_events(GVirStream *stream); -- 2.14.1
--- libvirt-gobject/libvirt-gobject-stream.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libvirt-gobject/libvirt-gobject-stream.c b/libvirt-gobject/libvirt-gobject-stream.c index b6bf774..296c00e 100644 --- a/libvirt-gobject/libvirt-gobject-stream.c +++ b/libvirt-gobject/libvirt-gobject-stream.c @@ -396,7 +396,7 @@ stream_sink(virStreamPtr st G_GNUC_UNUSED, * * Receive the entire data stream, sending the data to the * requested data sink. This is simply a convenient alternative - * to virStreamRecv, for apps that do blocking-I/o. + * to #gvir_vir_stream_receive, for apps that do blocking-I/o. * * Returns: the number of bytes consumed or -1 upon error */ @@ -512,7 +512,7 @@ stream_source(virStreamPtr st G_GNUC_UNUSED, * * Send the entire data stream, sending the data to the * requested data source. This is simply a convenient alternative - * to virStreamRecv, for apps that do blocking-I/o. + * to #gvir_stream_send, for apps that do blocking-I/o. * * Returns: the number of bytes consumed or -1 upon error */ -- 2.14.1
Fix doc and use a proper variable name --- libvirt-gobject/libvirt-gobject-stream.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/libvirt-gobject/libvirt-gobject-stream.c b/libvirt-gobject/libvirt-gobject-stream.c index 296c00e..93788b5 100644 --- a/libvirt-gobject/libvirt-gobject-stream.c +++ b/libvirt-gobject/libvirt-gobject-stream.c @@ -440,15 +440,15 @@ gvir_stream_receive_all(GVirStream *self, * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. * - * Send data (up to @size bytes) from a stream. + * Send data (up to @size bytes) to a stream. * On error -1 is returned and @error is set accordingly. * - * gvir_stream_send() can return any number of bytes, up to - * @size. If more than @size bytes have been sendd, the additional - * data will be returned in future calls to gvir_stream_send(). + * gvir_stream_send() can send any number of bytes, up to + * @size. If less than @size bytes have been send, the additional + * data can be sent in future calls to gvir_stream_send(). * - * If there is no data available, a %G_IO_ERROR_WOULD_BLOCK error will be - * returned. + * If the receiving end would block, a %G_IO_ERROR_WOULD_BLOCK error + * will be returned. * * Returns: Number of bytes written. */ @@ -458,7 +458,7 @@ gssize gvir_stream_send(GVirStream *self, GCancellable *cancellable, GError **error) { - int got; + int sent; g_return_val_if_fail(GVIR_IS_STREAM(self), -1); g_return_val_if_fail(buffer != NULL, -1); @@ -468,17 +468,17 @@ gssize gvir_stream_send(GVirStream *self, if (g_cancellable_set_error_if_cancelled (cancellable, error)) return -1; - got = virStreamSend(self->priv->handle, buffer, size); + sent = virStreamSend(self->priv->handle, buffer, size); - if (got == -2) { /* blocking */ + if (sent == -2) { /* blocking */ g_set_error_literal(error, G_IO_ERROR, G_IO_ERROR_WOULD_BLOCK, _("virStreamSend call would block")); - } else if (got < 0) { + } else if (sent < 0) { g_set_error(error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT, - _("Got virStreamRecv error in %s"), G_STRFUNC); + _("Sent virStreamRecv error in %s"), G_STRFUNC); } - return got; + return sent; } struct stream_source_helper { -- 2.14.1
participants (1)
-
Guido Günther