diff --git a/TODO b/TODO
index 7a36e5b4..f540d142 100644
--- a/TODO
+++ b/TODO
@@ -2,7 +2,8 @@
- vips_object_unref_outputs() needs docs ... bindings will need it
-- vips_init() has a deprecation warning, bizarre
+- where should we explain VIPS_IMAGE_ADDR(), VIPS_REGION_ADDR(),
+ vips_region_region() etc.?
diff --git a/libvips/deprecated/wrapvips7.c b/libvips/deprecated/wrapvips7.c
index bcb15c91..f30d541f 100644
--- a/libvips/deprecated/wrapvips7.c
+++ b/libvips/deprecated/wrapvips7.c
@@ -36,7 +36,7 @@
TODO:
- masks would be hard, vips8 won't really have these
- - keep for testing, mostly ... iofuncs/init.c has a commeted-out
+ - keep for testing, mostly ... iofuncs/init.c has a commented-out
call to init this thing
*/
diff --git a/libvips/include/vips/generate.h b/libvips/include/vips/generate.h
index f7af6884..ed81c89d 100644
--- a/libvips/include/vips/generate.h
+++ b/libvips/include/vips/generate.h
@@ -56,10 +56,9 @@ typedef void (*VipsSinkNotify)( VipsImage *im, VipsRect *rect, void *a );
int vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
int tile_width, int tile_height, int max_tiles,
int priority,
- VipsSinkNotify notify, void *a );
+ VipsSinkNotify notify_fn, void *a );
int vips_sink_memory( VipsImage *im );
-int vips_sink_memory2( VipsImage *image );
void *vips_start_one( VipsImage *out, void *a, void *b );
int vips_stop_one( void *seq, void *a, void *b );
diff --git a/libvips/iofuncs/generate.c b/libvips/iofuncs/generate.c
index f23dccc1..e9467ce9 100644
--- a/libvips/iofuncs/generate.c
+++ b/libvips/iofuncs/generate.c
@@ -112,12 +112,12 @@
* SECTION: generate
* @short_description: calculate pixels and pixel buffers
* @stability: Stable
- * @see_also: image,
- * region
+ * @see_also: VipsImage,
+ * VipsRegion
* @include: vips/vips.h
*
- * These functions let you generate regions of pixels in an image
- * processing operation, and ask for regions of image to be calculated.
+ * These functions let you attach generate functions to images
+ * and ask for regions of images to be calculated.
*/
/* Max number of images we can handle.
@@ -349,7 +349,7 @@ vips__demand_hint_array( VipsImage *image,
* @image prefers to supply pixels according to @hint.
*
* Operations can set demand hints, that is, hints to the VIPS IO system about
- * the type of region geometry this operation works best with. For example,
+ * the type of region geometry they work best with. For example,
* operations which transform coordinates will usually work best with
* %VIPS_DEMAND_STYLE_SMALLTILE, operations which work on local windows of
* pixels will like %VIPS_DEMAND_STYLE_FATSTRIP.
@@ -642,13 +642,14 @@ write_vips( VipsRegion *region, VipsRect *area, void *a, void *b )
*
* Generates an image. The action depends on the image type.
*
- * For images opened with "p", vips_image_generate() just attaches the
- * start/generate/stop callbacks and returns.
+ * For images created with vips_image_new(), vips_image_generate() just
+ * attaches the start/generate/stop callbacks and returns.
*
- * For "t" images, memory is allocated for the whole image and it is entirely
- * generated using vips_sink().
+ * For images created with vips_image_new_memory(), memory is allocated for
+ * the whole image and it is entirely generated using vips_sink_memory().
*
- * For "w" images, memory for a few scanlines is allocated and
+ * For images created with vips_image_new_temp_file() and friends, memory for
+ * a few scanlines is allocated and
* vips_sink_disc() used to generate the image in small chunks. As each
* chunk is generated, it is written to disc.
*
diff --git a/libvips/iofuncs/header.c b/libvips/iofuncs/header.c
index 99bdcf87..197865cc 100644
--- a/libvips/iofuncs/header.c
+++ b/libvips/iofuncs/header.c
@@ -71,41 +71,22 @@
* SECTION: header
* @short_description: get, set and walk image headers
* @stability: Stable
- * @see_also: meta,
- * check
+ * @see_also: type
* @include: vips/vips.h
*
* These functions let you get at image header data (including metadata) in a
- * uniform way. They are handy for language bindings but less useful for C
- * users.
+ * uniform way.
*
- * They first search the
- * VIPS header
- * fields (see image), then search for
- * a metadata field of that name (see
- * meta).
* Use vips_image_get_typeof() to test for the
* existance and #GType
* of a header field.
*
- * See meta
- * for a set of functions for adding new metadata to an image.
- */
-
-/**
- * SECTION: meta
- * @short_description: get and set image metadata
- * @stability: Stable
- * @see_also: header
- * @include: vips/vips.h
- *
- * You can attach arbitrary metadata to images. VipsMetadata is copied as images
+ * You can attach arbitrary metadata to images. Metadata is copied as images
* are processed, so all images which used this image as input, directly or
* indirectly, will have this same bit of metadata attached to them. Copying
* is implemented with reference-counted pointers, so it is efficient, even for
* large items of data. This does however mean that metadata items need to be
- * immutable. VipsMetadata
- * is handy for things like ICC profiles or EXIF data.
+ * immutable. Metadata is handy for things like ICC profiles or EXIF data.
*
* Various convenience functions (eg. vips_image_set_int()) let you easily
* attach
@@ -120,13 +101,14 @@
* If you save an image in VIPS format, all metadata (with a restriction, see
* below) is automatically saved for you in a block of XML at the end of the
* file. When you load a VIPS image, the metadata is restored. You can use the
- * 'edvips' command-line tool to extract or replace this block of XML.
+ * `vipsedit` command-line tool to extract or replace this block of XML.
*
- * VIPS metadata is based on GValue. See the docs for that system if you want
+ * VIPS metadata is based on %GValue. See the docs for that system if you want
* to do fancy stuff such as defining a new metadata type.
- * VIPS defines a new GValue called "vips_save_string", a variety of string. If
- * your GValue can be transformed to vips_save_string, it will be saved and
- * loaded to and from VIPS files for you.
+ * VIPS defines a new %GValue called `vips_save_string`, a variety of string,
+ * see vips_value_set_save_string().
+ * If your %GValue can be transformed to `vips_save_string`, it will be
+ * saved and loaded to and from VIPS files for you.
*
* VIPS provides a couple of base classes which implement
* reference-counted areas of memory. If you base your metadata on one of
@@ -201,7 +183,11 @@ const guint64 vips__image_sizeof_bandformat[] = {
2 * sizeof( double ) /* VIPS_FORMAT_DPCOMPLEX */
};
-/* Return number of bytes for a band format, or -1 on error.
+/**
+ * vips_format_sizeof:
+ * @format: format type
+ *
+ * Returns: number of bytes for a band format, or -1 on error.
*/
guint64
vips_format_sizeof( VipsBandFormat format )
@@ -335,38 +321,69 @@ meta_init( VipsImage *im )
}
}
+/**
+ * vips_image_get_width:
+ * @image: image to get from
+ *
+ * Returns: the number of pixels across the image.
+ */
int
vips_image_get_width( const VipsImage *image )
{
return( image->Xsize );
}
+/**
+ * vips_image_get_height:
+ * @image: image to get from
+ *
+ * Returns: the number of pixels down the image.
+ */
int
vips_image_get_height( const VipsImage *image )
{
return( image->Ysize );
}
+/**
+ * vips_image_get_bands:
+ * @image: image to get from
+ *
+ * Returns: the number of bands (channels) in the image.
+ */
int
vips_image_get_bands( const VipsImage *image )
{
return( image->Bands );
}
+/**
+ * vips_image_get_format:
+ * @image: image to get from
+ *
+ * Returns: the format of each band element.
+ */
VipsBandFormat
vips_image_get_format( const VipsImage *image )
{
return( image->BandFmt );
}
+/**
+ * vips_image_get_coding:
+ * @image: image to get from
+ *
+ * Returns: the image coding
+ */
VipsCoding
vips_image_get_coding( const VipsImage *image )
{
return( image->Coding );
}
-/* vips_image_get_interpretation:
- * @image: image to guess for
+/**
+ * vips_image_get_interpretation:
+ * @image: image to get from
*
* Return the #VipsInterpretation set in the image header.
* Use vips_image_guess_interpretation() if you want a sanity-checked value.
@@ -400,11 +417,12 @@ vips_image_default_interpretation( const VipsImage *image )
return( VIPS_INTERPRETATION_MULTIBAND );
}
-/* vips_image_guess_interpretation:
+/**
+ * vips_image_guess_interpretation:
* @image: image to guess for
*
- * Return the #VipsInterpretation for an image, guessing a default value if
- * the set value looks wrong.
+ * Return the #VipsInterpretation for an image, guessing a sane value if
+ * the set value looks crazy.
*
* Returns: a sensible #VipsInterpretation for the image.
*/
@@ -510,42 +528,90 @@ vips_image_guess_interpretation( const VipsImage *image )
return( vips_image_default_interpretation( image ) );
}
+/**
+ * vips_image_get_xres:
+ * @image: image to get from
+ *
+ * Returns: the horizontal image resolution in pixels per millimeter.
+ */
double
vips_image_get_xres( const VipsImage *image )
{
return( image->Xres );
}
+/**
+ * vips_image_get_yres:
+ * @image: image to get from
+ *
+ * Returns: the vertical image resolution in pixels per millimeter.
+ */
double
vips_image_get_yres( const VipsImage *image )
{
return( image->Yres );
}
+/**
+ * vips_image_get_xoffset:
+ * @image: image to get from
+ *
+ * Returns: the horizontal position of the image origin, in pixels.
+ */
int
vips_image_get_xoffset( const VipsImage *image )
{
return( image->Xoffset );
}
+/**
+ * vips_image_get_yoffset:
+ * @image: image to get from
+ *
+ * Returns: the vertical position of the image origin, in pixels.
+ */
int
vips_image_get_yoffset( const VipsImage *image )
{
return( image->Yoffset );
}
+/**
+ * vips_image_get_filename:
+ * @image: image to get from
+ *
+ * Returns: the name of the file the image was loaded from.
+ */
const char *
vips_image_get_filename( const VipsImage *image )
{
return( image->filename );
}
+/**
+ * vips_image_get_mode:
+ * @image: image to get from
+ *
+ * Image modes are things like `"t"`, meaning a memory buffer, and `"p"`
+ * meaning a delayed computation.
+ *
+ * Returns: the image mode.
+ */
const char *
vips_image_get_mode( const VipsImage *image )
{
return( image->mode );
}
+/**
+ * vips_image_get_scale:
+ * @image: image to get from
+ *
+ * Matrix images can have an optional `scale` field for use by integer
+ * convolution.
+ *
+ * Returns: the scale.
+ */
double
vips_image_get_scale( const VipsImage *array )
{
@@ -558,6 +624,15 @@ vips_image_get_scale( const VipsImage *array )
return( scale );
}
+/**
+ * vips_image_get_offset:
+ * @image: image to get from
+ *
+ * Matrix images can have an optional `offset` field for use by integer
+ * convolution.
+ *
+ * Returns: the offset.
+ */
double
vips_image_get_offset( const VipsImage *array )
{
@@ -571,7 +646,7 @@ vips_image_get_offset( const VipsImage *array )
}
/**
- * vips_image_get_data: (skip)
+ * vips_image_get_data:
* @image: image to get data for
*
* Return a pointer to the image's pixel data, if possible. This can involve
@@ -607,7 +682,7 @@ vips_image_get_data( VipsImage *image )
* Normally you copy the fields from your input images with
* vips_image_pipelinev() and then make
* any adjustments you need, but if you are creating an image from scratch,
- * for example im_black() or im_jpeg2vips(), you do need to set all the
+ * for example vips_black() or vips_jpegload(), you do need to set all the
* fields yourself.
*
* See also: vips_image_pipelinev().
@@ -724,24 +799,22 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
* vips_image_set:
* @image: image to set the metadata on
* @field: the name to give the metadata
- * @value: the GValue to copy into the image
+ * @value: the %GValue to copy into the image
*
* Set a piece of metadata on @image. Any old metadata with that name is
- * destroyed. The GValue is copied into the image, so you need to unset the
+ * destroyed. The %GValue is copied into the image, so you need to unset the
* value when you're done with it.
*
* For example, to set an integer on an image (though you would use the
- * convenience function vips_image_set_int() in practice), you would need:
+ * convenience function vips_image_set_int() in practice), you would do:
*
* |[
* GValue value = { 0 };
*
- * g_value_init( &value, G_TYPE_INT );
- * g_value_set_int( &value, 42 );
- * vips_image_set( image, field, &value );
- * g_value_unset( &value );
- *
- * return( 0 );
+ * g_value_init (&value, G_TYPE_INT);
+ * g_value_set_int (&value, 42);
+ * vips_image_set (image, field, &value);
+ * g_value_unset (&value);
* ]|
*
* See also: vips_image_get().
@@ -764,15 +837,14 @@ vips_image_set( VipsImage *image, const char *field, GValue *value )
* vips_image_get:
* @image: image to get the field from from
* @field: the name to give the metadata
- * @value_copy: the GValue is copied into this
+ * @value_copy: the %GValue is copied into this
*
* Fill @value_copy with a copy of the header field. @value_copy must be zeroed
* but uninitialised.
*
* This will return -1 and add a message to the error buffer if the field
* does not exist. Use vips_image_get_typeof() to test for the
- * existence
- * of a field first if you are not certain it will be there.
+ * existence of a field first if you are not certain it will be there.
*
* For example, to read a double from an image (though of course you would use
* vips_image_get_double() in practice):
@@ -781,22 +853,20 @@ vips_image_set( VipsImage *image, const char *field, GValue *value )
* GValue value = { 0 };
* double d;
*
- * if( vips_image_get( image, field, &value ) )
- * return( -1 );
+ * if (vips_image_get (image, field, &value))
+ * return -1;
*
- * if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
+ * if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
* vips_error( "mydomain",
- * _( "field \"%s\" is of type %s, not double" ),
+ * _("field \"%s\" is of type %s, not double"),
* field,
- * g_type_name( G_VALUE_TYPE( &value ) ) );
- * g_value_unset( &value );
- * return( -1 );
+ * g_type_name (G_VALUE_TYPE (&value)));
+ * g_value_unset (&value);
+ * return -1;
* }
*
- * d = g_value_get_double( &value );
- * g_value_unset( &value );
- *
- * return( 0 );
+ * d = g_value_get_double (&value);
+ * g_value_unset (&value);
* ]|
*
* See also: vips_image_get_typeof(), vips_image_get_double().
@@ -875,12 +945,12 @@ vips_image_get( const VipsImage *image, const char *field, GValue *value_copy )
* @image: image to test
* @field: the name to search for
*
- * Read the GType for a header field. Returns zero if there is no
+ * Read the %GType for a header field. Returns zero if there is no
* field of that name.
*
* See also: vips_image_get().
*
- * Returns: the GType of the field, or zero if there is no
+ * Returns: the %GType of the field, or zero if there is no
* field of that name.
*/
GType
@@ -945,7 +1015,7 @@ vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a )
}
/**
- * vips_image_map: (skip)
+ * vips_image_map:
* @image: image to map over
* @fn: function to call for each header field
* @a: user data for function
@@ -1101,7 +1171,7 @@ vips_image_set_blob( VipsImage *image, const char *field,
}
/**
- * vips_image_get_blob: (skip)
+ * vips_image_get_blob:
* @image: image to get the metadata from
* @field: metadata name
* @data: pointer to area of memory
@@ -1333,7 +1403,7 @@ vips_image_set_string( VipsImage *image, const char *field, const char *str )
* vips_image_get_as_string:
* @image: image to get the header field from
* @field: field name
- * @out: return field value as string
+ * @out: (transfer full): return field value as string
*
* Gets @out from @im under the name @field.
* This function will read any field, returning it as a printable string.
@@ -1378,7 +1448,7 @@ vips_image_get_as_string( const VipsImage *image,
* vips_image_history_printf:
* @image: add history line to this image
* @format: printf() format string
- * @Varargs: arguments to format string
+ * @...: arguments to format string
*
* Add a line to the image history. The @format and arguments are expanded, the
* date and time is appended prefixed with a hash character, and the whole
@@ -1387,15 +1457,14 @@ vips_image_get_as_string( const VipsImage *image,
* For example:
*
* |[
- * vips_image_history_printf( image, "vips im_invert %s %s",
- * in->filename, out->filename );
+ * vips_image_history_printf (image, "vips invert %s %s",
+ * in->filename, out->filename);
* ]|
*
* Might add the string
*
* |[
- * "vips im_invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35
- * 2009\n"
+ * "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n"
* ]|
*
* VIPS operations don't add history lines for you because a single action at
@@ -1486,7 +1555,7 @@ vips_image_history_args( VipsImage *image,
*
* See also: vips_image_history_printf().
*
- * Returns: The history of @image as a C string. Do not free!
+ * Returns: (transfer none): The history of @image as a C string. Do not free!
*/
const char *
vips_image_get_history( VipsImage *image )
diff --git a/libvips/iofuncs/image.c b/libvips/iofuncs/image.c
index 4ce62305..02050ae8 100644
--- a/libvips/iofuncs/image.c
+++ b/libvips/iofuncs/image.c
@@ -58,7 +58,10 @@
* SECTION: image
* @short_description: the VIPS image class
* @stability: Stable
- * @see_also: region
+ * @see_also: header
+ * VipsRegion
+ * generate
+ * VipsOperation
* @include: vips/vips.h
*
* The image class and associated types and macros.
@@ -78,7 +81,7 @@
* height and bands. Each dimension can be up to 2 ** 31 pixels (or band
* elements). An image has a format, meaning the machine number type used
* to represent each value. VIPS supports 10 formats, from 8-bit unsigned
- * integer up to 128-bit double complex, see vips_image_get_format()..
+ * integer up to 128-bit double complex, see vips_image_get_format().
*
* In VIPS, images are uninterpreted arrays, meaning that from the point of
* view of most operations, they are just large collections of numbers.
@@ -96,7 +99,7 @@
* VIPS has a feature to help (a little) with this: it sets a
* #VipsInterpretation hint for each image (see
* vips_image_get_interpretation()); a hint which says how pixels should
- * probably be interpreted. For example, vips_Lab2XYZ() will set the
+ * be interpreted. For example, vips_Lab2XYZ() will set the
* interpretation of the output image to #VIPS_INTERPRETATION_XYZ. A
* few utility operations will also use interpretation as a guide. For
* example, you can give vips_colourspace() an input image and a desired
@@ -108,6 +111,11 @@
* to formatted memory buffers (with vips_image_write_to_buffer()) and to
* C-style memory arrays (with vips_image_write_to_memory().
*
+ * You can also write image to other images. Create, for example, a temporary
+ * disc image with vips_image_new_temp_file(), then write your image to that
+ * with vips_image_write(). You can create several other types of image and
+ * write to them, see vips_image_new_memory(), for example.
+ *
* See operation for an introduction to
* running operations on images, see header for getting and setting image
@@ -152,8 +160,8 @@
* @VIPS_DEMAND_STYLE_THINSTRIP: demand in thin (typically 1 pixel high) strips
* @VIPS_DEMAND_STYLE_ANY: demand geometry does not matter
*
- * See vips_image_pipelinev(). Operations can hint to the VIPS image IO system about
- * the kind of demand geometry they prefer.
+ * See vips_image_pipelinev(). Operations can hint to the VIPS image IO
+ * system about the kind of demand geometry they prefer.
*
* These demand styles are given below in order of increasing
* restrictiveness. When demanding output from a pipeline,
@@ -213,7 +221,7 @@
* of VIPS to help them show images to the user in a meaningful way.
* Operations do not use these values to decide their action.
*
- * The gaps in the numbering are historical and must be maintained. Allocate
+ * The gaps in numbering are historical and must be maintained. Allocate
* new numbers from the end.
*/
@@ -233,7 +241,7 @@
*
* The format used for each band element.
*
- * Each corresponnds to a native C type for the current machine. For example,
+ * Each corresponds to a native C type for the current machine. For example,
* #VIPS_FORMAT_USHORT is unsigned short.
*/
@@ -322,9 +330,9 @@
*
* If VIPS_DEBUG is defined, you get a version that checks bounds for you.
*
- * See also: VIPS_REGION_ADDR().
+ * See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR().
*
- * Returns: The address of pixel (x,y) in the image.
+ * Returns: The address of pixel (@X,@Y) in @I.
*/
/**
@@ -341,9 +349,9 @@
* If VIPS_DEBUG is defined, you get a version that checks bounds and image
* type for you.
*
- * See also: VIPS_IMAGE_ADDR().
+ * See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix().
*
- * Returns: The address of pixel (x,y) in the image.
+ * Returns: The address of pixel (@X,@Y) in @I.
*/
/* Our signals.
@@ -1245,8 +1253,8 @@ vips_image_class_init( VipsImageClass *class )
* 128 area of pixels) during image computation.
*
* You can use this signal to update user-interfaces with progress
- * feedback. Beware of updating too frequently: there will usually
- * need to be some mechanism to limit update frequency.
+ * feedback. Beware of updating too frequently: you will usually
+ * need some throttling mechanism.
*
* Use vips_image_set_progress() to turn on progress reporting for an
* image.
@@ -1285,9 +1293,10 @@ vips_image_class_init( VipsImageClass *class )
* @image: the image that was calculated
* @result: set to non-zero to indicate error
*
- * The ::written signal is emitted when an image is written to. It is
- * used by things like vips_image_new_mode("x.jpg", "w") to do the
- * final write of @image.
+ * The ::written signal is emitted just after an image has been
+ * written to. It is
+ * used by vips to implement things like write to foreign file
+ * formats.
*/
vips_image_signals[SIG_WRITTEN] = g_signal_new( "written",
G_TYPE_FROM_CLASS( class ),
@@ -1662,8 +1671,9 @@ vips_image_temp_name( void )
* If you write to one of these images, vips will just attach some callbacks,
* no pixels will be generated.
*
- * It is the equivalent of
- * vips_image_new_mode() with @mode "p".
+ * Write pixels to an image with vips_image_generate() or
+ * vips_image_write_line(). Write a whole image to another image with
+ * vips_image_write().
*
* Returns: the new #VipsImage, or %NULL on error.
*/
@@ -1716,10 +1726,6 @@ vips_image_new_mode( const char *filename, const char *mode )
* vips_image_new_memory() creates a new #VipsImage which, when written to, will
* create a memory image.
*
- * It is a convenience function for
- * vips_image_new_mode() with @filename set by vips_image_temp_name() and
- * @mode "t".
- *
* See also: vips_image_new().
*
* Returns: the new #VipsImage, or %NULL on error.
@@ -2080,7 +2086,7 @@ vips_image_new_matrixv( int width, int height, ... )
*
* Sets the delete_on_close flag for the image. If this flag is set, when
* @image is finalized, the filename held in @image->filename at the time of
- * this call is unlinked.
+ * this call is deleted.
*
* This function is clearly extremely dangerous, use with great caution.
*
@@ -2102,8 +2108,9 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close )
* vips_image_new_temp_file:
* @format: format of file
*
- * Make a "w" disc #VipsImage which will be automatically unlinked when it is
- * destroyed. @format is something like "%s.v" for a vips file.
+ * Make a #VipsImage which, when written to, will create a temporary file on
+ * disc. The file will be automatically deleted when the image is destroyed.
+ * @format is something like "%s.v" for a vips file.
*
* The file is created in the temporary directory. This is set with the
* environment variable TMPDIR. If this is not set, then on Unix systems, vips
@@ -2113,6 +2120,8 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close )
* vips uses g_mkstemp() to make the temporary filename. They generally look
* something like "vips-12-EJKJFGH.v".
*
+ * See also: vips_image_new().
+ *
* Returns: the new #VipsImage, or %NULL on error.
*/
VipsImage *
@@ -2292,10 +2301,10 @@ vips_image_write_to_buffer( VipsImage *in,
/**
* vips_image_write_to_memory:
* @in: image to write
- * @buf: return buffer start here
+ * @buf: (transfer full): return buffer start here
* @len: return buffer length here
*
- * Writes @in to memory as a simple, unformatted array.
+ * Writes @in to memory as a simple, unformatted C-style array.
*
* The caller is responsible for freeing memory.
*
@@ -2381,7 +2390,7 @@ vips_image_decode( VipsImage *in, VipsImage **out )
* @bands: predict bands here
* @format: predict format here
*
- * We often need to know what an image will decode to without actuaklly
+ * We often need to know what an image will decode to without actually
* decoding it, for example, in arg checking.
*
* See also: vips_image_decode().
@@ -2514,7 +2523,7 @@ vips_image_ispartial( VipsImage *image )
*
* Normally this function is called for you by vips_image_generate() or
* vips_image_write_line(). You will need to call it yourself if you plan to
- * write directly to the ->data member of a "t" image.
+ * write directly to the ->data member of a memory image.
*
* Returns: 0 on success, or -1 on error.
*/
diff --git a/libvips/iofuncs/init.c b/libvips/iofuncs/init.c
index c2419795..bb6e8fe8 100644
--- a/libvips/iofuncs/init.c
+++ b/libvips/iofuncs/init.c
@@ -811,7 +811,7 @@ guess_prefix( const char *argv0, const char *name )
*
* See also: vips_guess_libdir().
*
- * Returns: the install prefix as a static string, do not free.
+ * Returns: (transfer none): the install prefix as a static string, do not free.
*/
const char *
vips_guess_prefix( const char *argv0, const char *env_name )
@@ -876,7 +876,7 @@ vips_guess_prefix( const char *argv0, const char *env_name )
*
* See also: vips_guess_prefix().
*
- * Returns: the libdir as a static string, do not free.
+ * Returns: (transfer none): the libdir as a static string, do not free.
*/
const char *
vips_guess_libdir( const char *argv0, const char *env_name )
diff --git a/libvips/iofuncs/sink.c b/libvips/iofuncs/sink.c
index ca9bca14..e950ffdf 100644
--- a/libvips/iofuncs/sink.c
+++ b/libvips/iofuncs/sink.c
@@ -335,8 +335,9 @@ vips_sink_base_progress( void *a )
* @a: user data
* @b: user data
*
- * Loops over an image. @generate is called for every pixel in the image, with
- * the @reg argument being a region of pixels for processing.
+ * Loops over an image. @generate_fn is called for every
+ * pixel in the image, with
+ * the @reg argument being a region of calculated pixels.
*
* Each set of pixels is @tile_width by @tile_height pixels (less at the
* image edges). This is handy for things like writing a tiled TIFF image,
@@ -398,9 +399,10 @@ vips_sink_tile( VipsImage *im,
* @a: user data
* @b: user data
*
- * Loops over an image. @generate is called for every pixel in the image, with
- * the @reg argument being a region of pixels for processing. vips_sink() is
- * used to implement operations like #VipsAvg which have no image output.
+ * Loops over an image. @generate_fn is called for every pixel in
+ * the image, with
+ * the @reg argument being a region of calculated pixels. vips_sink() is
+ * used to implement operations like vips_avg() which have no image output.
*
* Each set of pixels is sized according to the requirements of the image
* pipeline that generated @im.
diff --git a/libvips/iofuncs/sinkdisc.c b/libvips/iofuncs/sinkdisc.c
index 443b7128..8c1fd067 100644
--- a/libvips/iofuncs/sinkdisc.c
+++ b/libvips/iofuncs/sinkdisc.c
@@ -451,7 +451,7 @@ write_free( Write *write )
* @a: client data
*
* The function should write the pixels in @area from @region. @a is the
- * value passed into vips_discsink().
+ * value passed into vips_sink_disc().
*
* See also: vips_sink_disc().
*
@@ -472,7 +472,8 @@ write_free( Write *write )
* sections in top-to-bottom order, and there are never any gaps.
*
* This operation is handy for making image sinks which output to things like
- * disc files.
+ * disc files. Things like vips_jpegsave(), for example, use this to write
+ * images to files in JPEG format.
*
* See also: vips_concurrency_set().
*
diff --git a/libvips/iofuncs/sinkmemory.c b/libvips/iofuncs/sinkmemory.c
index fca55963..97bf815c 100644
--- a/libvips/iofuncs/sinkmemory.c
+++ b/libvips/iofuncs/sinkmemory.c
@@ -313,10 +313,10 @@ sink_memory_init( SinkMemory *memory, VipsImage *image )
* vips_sink_memory:
* @im: generate this image to memory
*
- * Loops over an image, generating it to a memory buffer attached to the
- * image.
+ * Loops over @im, generating it to a memory buffer attached to @im. It is
+ * used by vips to implement writing to a memory buffer.
*
- * See also: vips_sink(), vips_get_tile_size().
+ * See also: vips_sink(), vips_get_tile_size(), vips_image_new_memory().
*
* Returns: 0 on success, or -1 on error.
*/
diff --git a/libvips/iofuncs/sinkscreen.c b/libvips/iofuncs/sinkscreen.c
index 1c49efd9..29e4c512 100644
--- a/libvips/iofuncs/sinkscreen.c
+++ b/libvips/iofuncs/sinkscreen.c
@@ -1047,11 +1047,11 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop )
* @tile_height: tile height
* @max_tiles: maximum tiles to cache
* @priority: rendering priority
- * @notify: pixels are ready notification callback
+ * @notify_fn: pixels are ready notification callback
* @a: client data for callback
*
* This operation renders @in in the background, making pixels available on
- * @out as they are calculated. The @notify callback is run every time a new
+ * @out as they are calculated. The @notify_fn callback is run every time a new
* set of pixels are available. Calculated pixels are kept in a cache with
* tiles sized @tile_width by @tile_height pixels and with at most @max_tiles
* tiles.
@@ -1071,15 +1071,15 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop )
* currently in cache for that #VipsRect (check @mask to see which parts of the
* #VipsRect are valid). Any pixels in the #VipsRect which are not in
* cache are added
- * to a queue, and the @notify callback will trigger when those pixels are
+ * to a queue, and the @notify_fn callback will trigger when those pixels are
* ready.
*
- * The @notify callback is run from one of the background threads. In the
+ * The @notify_fn callback is run from one of the background threads. In the
* callback
* you need to somehow send a message to the main thread that the pixels are
* ready. In a glib-based application, this is easily done with g_idle_add().
*
- * If @notify is %NULL then vips_sink_screen() runs synchronously.
+ * If @notify_fn is %NULL then vips_sink_screen() runs synchronously.
* vips_region_prepare() on @out will always block until the pixels have been
* calculated.
*
@@ -1093,7 +1093,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
int tile_width, int tile_height,
int max_tiles,
int priority,
- VipsSinkNotify notify, void *a )
+ VipsSinkNotify notify_fn, void *a )
{
Render *render;
@@ -1125,7 +1125,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
}
if( !(render = render_new( in, out, mask,
- tile_width, tile_height, max_tiles, priority, notify, a )) )
+ tile_width, tile_height, max_tiles, priority, notify_fn, a )) )
return( -1 );
VIPS_DEBUG_MSG( "vips_sink_screen: max = %d, %p\n", max_tiles, render );
diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c
index 1e9c6f34..af7ff785 100644
--- a/libvips/iofuncs/type.c
+++ b/libvips/iofuncs/type.c
@@ -59,10 +59,10 @@
* SECTION: type
* @short_description: basic types
* @stability: Stable
- * @see_also: operation
+ * @see_also: header
* @include: vips/vips.h
*
- * A selection of GType defintions used by VIPS.
+ * A selection of %GType defintions used by VIPS.
*/
/* A very simple boxed type for testing. Just an int.
diff --git a/libvips/iofuncs/vips.c b/libvips/iofuncs/vips.c
index ed80b20f..6502f0d6 100644
--- a/libvips/iofuncs/vips.c
+++ b/libvips/iofuncs/vips.c
@@ -92,7 +92,7 @@
* SECTION: vips
* @short_description: startup, shutdown, version
* @stability: Stable
- * @see_also: operation
+ * @see_also: VipsOperation
* @include: vips/vips.h
*
* Start VIPS up, shut VIPS down, get version information, relocation.