From 96cdc5ef01a06d131fd326d15c4b8bd8af8afb74 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Mon, 30 Dec 2019 16:28:39 +0000 Subject: [PATCH] revise docs for source / target --- doc/libvips-docs.xml.in | 2 +- libvips/foreign/foreign.c | 1 + libvips/include/vips/connection.h | 22 +++++++++++----------- libvips/iofuncs/connection.c | 22 ++++++++++++++++++++-- libvips/iofuncs/source.c | 2 +- libvips/iofuncs/threadpool.c | 1 + 6 files changed, 35 insertions(+), 15 deletions(-) diff --git a/doc/libvips-docs.xml.in b/doc/libvips-docs.xml.in index 26226f54..f151e43c 100644 --- a/doc/libvips-docs.xml.in +++ b/doc/libvips-docs.xml.in @@ -61,7 +61,7 @@ - + diff --git a/libvips/foreign/foreign.c b/libvips/foreign/foreign.c index 5df33751..aec3337a 100644 --- a/libvips/foreign/foreign.c +++ b/libvips/foreign/foreign.c @@ -77,6 +77,7 @@ * @stability: Stable * @see_also: image * @include: vips/vips.h + * @title: VipsForeign * * This set of operations load and save images in a variety of formats. * diff --git a/libvips/include/vips/connection.h b/libvips/include/vips/connection.h index 822de017..66cd5474 100644 --- a/libvips/include/vips/connection.h +++ b/libvips/include/vips/connection.h @@ -86,8 +86,8 @@ typedef struct _VipsConnectionClass { GType vips_connection_get_type( void ); -const char *vips_connection_filename( VipsConnection *stream ); -const char *vips_connection_nick( VipsConnection *stream ); +const char *vips_connection_filename( VipsConnection *connection ); +const char *vips_connection_nick( VipsConnection *connection ); #define VIPS_TYPE_SOURCE (vips_source_get_type()) #define VIPS_SOURCE( obj ) \ @@ -107,7 +107,7 @@ const char *vips_connection_nick( VipsConnection *stream ); /* Read from something like a socket, file or memory area and present the data * with a unified seek / read / map interface. * - * During the header phase, we save data from unseekable streams in a buffer + * During the header phase, we save data from unseekable sources in a buffer * so readers can rewind and read again. We don't buffer data during the * decode stage. */ @@ -117,7 +117,7 @@ typedef struct _VipsSource { /* We have two phases: * * During the header phase, we save bytes read from the input (if this - * is an unseekable stream) so that we can rewind and try again, if + * is an unseekable source) so that we can rewind and try again, if * necessary. * * Once we reach decode phase, we no longer support rewind and the @@ -126,7 +126,7 @@ typedef struct _VipsSource { gboolean decode; /* TRUE if this input is something like a pipe. These don't support - * stream or map -- all you can do is read() bytes sequentially. + * seek or map -- all you can do is read() bytes sequentially. * * If you attempt to map or get the size of a pipe-style input, it'll * get read entirely into memory. Seeks will cause read up to the seek @@ -165,7 +165,7 @@ typedef struct _VipsSource { */ GByteArray *sniff; - /* For a memory stream, the blob we read from. + /* For a memory source, the blob we read from. */ VipsBlob *blob; @@ -182,7 +182,7 @@ typedef struct _VipsSourceClass { /* Subclasses can define these to implement other source methods. */ - /* Read from the stream into the supplied buffer, args exactly as + /* Read from the source into the supplied buffer, args exactly as * read(2). Set errno on error. * * We must return gint64, since ssize_t is often defined as unsigned @@ -193,7 +193,7 @@ typedef struct _VipsSourceClass { /* Seek to a certain position, args exactly as lseek(2). Set errno on * error. * - * Unseekable streams should always return -1. VipsSource will then + * Unseekable sources should always return -1. VipsSource will then * seek by _read()ing bytes into memory as required. * * We have to use int64 rather than off_t, since we must work on @@ -289,11 +289,11 @@ typedef struct _VipsTarget { /*< private >*/ - /* This stream should write to memory. + /* This target should write to memory. */ gboolean memory; - /* The stream has been finished and can no longer be written. + /* The target has been finished and can no longer be written. */ gboolean finished; @@ -324,7 +324,7 @@ typedef struct _VipsTargetClass { gint64 (*write)( VipsTarget *, const void *, size_t ); /* Output has been generated, so do any clearing up, - * eg. copy the bytes we saved in memory to the stream blob. + * eg. copy the bytes we saved in memory to the target blob. */ void (*finish)( VipsTarget * ); diff --git a/libvips/iofuncs/connection.c b/libvips/iofuncs/connection.c index a148ff07..5d0653e1 100644 --- a/libvips/iofuncs/connection.c +++ b/libvips/iofuncs/connection.c @@ -62,12 +62,17 @@ * @stability: Stable * @see_also: foreign * @include: vips/vips.h + * @title: VipsConnection * * A #VipsConnection is a source or sink of bytes for something like jpeg - * loading. It can be connected to a network socket, for example, or perhaps + * loading, see for example vips_jpegload_source(). + * + * It can be connected to a network socket, for example, or perhaps * a node.js stream, or to an area of memory. * - * Subclass to add other input sources. + * Subclass to add other input sources. Use #VipsSourceCustom and + * #VipsTargetCustom to make a source or target with action signals for + * ::read, ::write and ::seek. */ /** @@ -142,12 +147,25 @@ vips_connection_init( VipsConnection *connection ) connection->close_descriptor = -1; } +/** + * vips_connection_filename: + * @connection: connection to operate on + * + * Returns: any filename associated with this connection, or NULL. + */ const char * vips_connection_filename( VipsConnection *connection ) { return( connection->filename ); } +/** + * vips_connection_nick: + * @connection: connection to operate on + * + * Returns: a string describing this connection which could be displayed to a + * user. + */ const char * vips_connection_nick( VipsConnection *connection ) { diff --git a/libvips/iofuncs/source.c b/libvips/iofuncs/source.c index c9b248a6..489a928a 100644 --- a/libvips/iofuncs/source.c +++ b/libvips/iofuncs/source.c @@ -329,7 +329,7 @@ vips_source_class_init( VipsSourceClass *class ) VIPS_ARG_BOXED( class, "blob", 3, _( "Blob" ), - _( "blob to load from" ), + _( "Blob to load from" ), VIPS_ARGUMENT_OPTIONAL_INPUT, G_STRUCT_OFFSET( VipsSource, blob ), VIPS_TYPE_BLOB ); diff --git a/libvips/iofuncs/threadpool.c b/libvips/iofuncs/threadpool.c index b815d605..26aac114 100644 --- a/libvips/iofuncs/threadpool.c +++ b/libvips/iofuncs/threadpool.c @@ -85,6 +85,7 @@ * @stability: Stable * @see_also: generate * @include: vips/vips.h + * @title: VipsThreadpool * * vips_threadpool_run() loops a set of threads over an image. Threads take it * in turns to allocate units of work (a unit might be a tile in an image),