Merge branch 'master' of github.com:jcupitt/libvips

ChangeLog

@@ -7,6 +7,7 @@
 - more doc fixes
 - fix similarity rotate+scale, thanks Topochicho
 - fix 16-bit PNG save, thanks John
+- fix dzsave date on Windows, thanks John
 
 25/7/14 started 7.40.5
 - fix a race in im_maxpos_avg()

TODO

@@ -1,18 +1,17 @@
 - can we pick the vipsthumbnail int shrink factor more intelligently?
 
+- vips_resize() should use vipsthumbnail's block/cache/affine/sharpen chain
+
 - vips_object_unref_outputs() needs docs ... bindings will need it
  
 - rewrite im_conv() etc. as vips_conv()
 
   finally finish --disable-deprecated option
 
-
+- vips_object_unref_outputs() needs docs ... bindings will need it
-
+ 
-
+- where should we explain VIPS_IMAGE_ADDR(), VIPS_REGION_ADDR(),
-- vips_init() has a deprecation warning, bizarre
+  vips_region_region() etc.?
-
-- vips_affine() for simple resize is slow at the command-line, since it has to
-  be non-seq ... make a seq version that can only up/down size
 
 
 

doc/reference/extending.xml

@@ -364,6 +364,10 @@ if( negative( in, &out, "image_max", 128, NULL ) )
       #VipsRect in _generate().
     </para>
 
+    <para>
+      Make zero-copy operations, like vips_insert(), with vips_region_region().
+    </para>
+
   </refsect1>
 
 </refentry>

doc/reference/using-C.xml

@@ -24,14 +24,14 @@
     </para>
 
     <para>
-      When your program starts, use <function>vips_init()</function> to set up 
+      When your program starts, use <function>VIPS_INIT()</function> to set up 
       the VIPS library. You should pass it the name of your program, usually 
       <literal>argv[0]</literal>. Use <function>vips_shutdown()</function> 
       when you exit. 
     </para>
 
     <para>
-      You can add the VIPS flags to your GObject command-line processing
+      You can add the VIPS flags to your %GObject command-line processing
       with vips_get_option_group(), see below.
     </para>
 
@@ -73,6 +73,13 @@
       C-style memory array. See vips_image_write_to_file() and friends.
     </para>
 
+    <para>
+      Use #VipsRegion to read pixels out of images. You can use 
+      VIPS_IMAGE_ADDR() as well, but this can need a large amount of 
+      memory to work. See <link linkend="extending">extending</link> 
+      for an introduxction to writing your own operations. 
+    </para>
+
     <para>
       VIPS keeps a log of error message, see  <link
       linkend="libvips-error">VIPS Error</link> to find out how to get and
@@ -100,7 +107,7 @@ main( int argc, char **argv )
 	double mean;
 	VipsImage *out;
 
-	if( vips_init( argv[0] ) )
+	if( VIPS_INIT( argv[0] ) )
 		vips_error_exit( NULL ); 
 
 	context = g_option_context_new( "hello infile outfile - VIPS demo" );

libvips/arithmetic/add.c

@@ -200,7 +200,7 @@ vips_add_init( VipsAdd *add )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/boolean.c

@@ -260,7 +260,7 @@ vips_booleanv( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>).
+ * <link linkend="libvips-arithmetic">arithmetic</link>).
  *
  * See also: vips_boolean_const().
  *

libvips/arithmetic/divide.c

@@ -254,7 +254,7 @@ vips_divide_init( VipsDivide *divide )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/math2.c

@@ -247,7 +247,7 @@ vips_math2v( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
+ * <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
  * result type.
  *
  * See also: vips_math2_const().

libvips/arithmetic/multiply.c

@@ -200,7 +200,7 @@ vips_multiply_init( VipsMultiply *multiply )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/relational.c

@@ -270,7 +270,7 @@ vips_relationalv( VipsImage *left, VipsImage *right, VipsImage **out,
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>).
+ * <link linkend="libvips-arithmetic">arithmetic</link>).
  *
  * To decide if pixels match exactly, that is have the same value in every
  * band, use vips_bandbool() after this operation to AND or OR image bands 

libvips/arithmetic/remainder.c

@@ -207,7 +207,7 @@ vips_remainder_init( VipsRemainder *remainder )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
+ * <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
  * result type.
  *
  * See also: vips_remainder_const(), vips_divide(), vips_round().

libvips/arithmetic/subtract.c

@@ -190,7 +190,7 @@ vips_subtract_init( VipsSubtract *subtract )
  *
  * The two input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

libvips/arithmetic/sum.c

@@ -179,7 +179,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
  * @n: number of input images
  * @...: %NULL-terminated list of optional named arguments
  *
- * This operation sums @in1 + @in2 and writes the result to @out. 
+ * This operation sums all images in @in and writes the result to @out. 
  *
  * If the images differ in size, the smaller images are enlarged to match the
  * largest by adding zero pixels along the bottom and right.
@@ -191,7 +191,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
  *
  * The input images are cast up to the smallest common format (see table 
  * Smallest common format in 
- * <link linkend="VIPS-arithmetic">arithmetic</link>), then the 
+ * <link linkend="libvips-arithmetic">arithmetic</link>), then the 
  * following table is used to determine the output type:
  *
  * <table>

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
 
  */

libvips/foreign/dzsave.c

@@ -45,6 +45,8 @@
  * 25/6/14
  * 	- stop on zip write >4gb, thanks bgilbert
  * 	- save metadata, see https://github.com/jcupitt/libvips/issues/137
+ * 18/8/14
+ * 	- use g_ date funcs, helps Windows
  */
 
 /*
@@ -809,17 +811,13 @@ write_vips_meta( VipsForeignSaveDz *dz )
 {
 	VipsObjectClass *class = VIPS_OBJECT_GET_CLASS( dz ); 
 
-	time_t now;
-	char time_string[50];
 	xmlDoc *doc;
+	GTimeVal now;
+	char *date;
 	char *dump;
 	int dump_size;
 	GsfOutput *out;
 
-	time( &now );
-	strftime( time_string, sizeof( time_string ), 
-		"%FT%TZ", gmtime( &now ) );
-
 	if( !(doc = xmlNewDoc( (xmlChar *) "1.0" )) ) { 
 		vips_error( class->nickname, "%s", _( "xml save error" ) );
 		return( -1 );
@@ -830,14 +828,19 @@ write_vips_meta( VipsForeignSaveDz *dz )
                 xmlFreeDoc( doc );
 		return( -1 );
 	}
+
+	g_get_current_time( &now );
+	date = g_time_val_to_iso8601( &now ); 
 	if( set_prop( dz, doc->children, "xmlns", 
 			"http://www.vips.ecs.soton.ac.uk/dzsave" ) ||  
-		set_prop( dz, doc->children, "date", time_string ) ||
+		set_prop( dz, doc->children, "date", date ) ||
 		set_prop( dz, doc->children, "version", VIPS_VERSION ) ||
 		write_vips_properties( dz, doc->children ) ) {
+		g_free( date );
                 xmlFreeDoc( doc );
                 return( -1 );
         }
+	g_free( date );
 
 	xmlDocDumpFormatMemory( doc, (xmlChar **) &dump, &dump_size, 1 );
 	if( !dump ) {

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 );

libvips/include/vips/internal.h

@@ -104,6 +104,8 @@ extern gboolean vips__cache_trace;
 
 void vips__cache_init( void );
 
+void vips__print_renders( void );
+
 void vips__type_leak( void );
 
 typedef int (*im__fftproc_fn)( VipsImage *, VipsImage *, VipsImage * );

libvips/include/vips/threadpool.h

@@ -131,8 +131,6 @@ int vips_threadpool_run( VipsImage *im,
 void vips_get_tile_size( VipsImage *im, 
 	int *tile_width, int *tile_height, int *nlines );
 
-void vips__print_renders( void );
-
 void vips_concurrency_set( int concurrency );
 int vips_concurrency_get( void );
 

libvips/include/vips/type.h

@@ -91,7 +91,6 @@ typedef struct _VipsArea {
 
 VipsArea *vips_area_copy( VipsArea *area );
 void vips_area_unref( VipsArea *area );
-void vips__type_leak( void );
 
 VipsArea *vips_area_new( VipsCallbackFn free_fn, void *data );
 VipsArea *vips_area_new_blob( VipsCallbackFn free_fn, 
@@ -198,8 +197,6 @@ int vips_value_set_array_object( GValue *value, int n );
  * vips_value_set_array_image(). They need to be declared after VipsImage. 
  */
 
-void vips__meta_init_types( void );
-
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

libvips/iofuncs/generate.c

@@ -112,12 +112,12 @@
  * SECTION: generate
  * @short_description: calculate pixels and pixel buffers
  * @stability: Stable
- * @see_also: <link linkend="libvips-image">image</link>, 
+ * @see_also: <link linkend="VipsImage">VipsImage</link>, 
- * <link linkend="libvips-region">region</link>
+ * <link linkend="VipsRegion">VipsRegion</link>
  * @include: vips/vips.h
  *
- * These functions let you generate regions of pixels in an image
+ * These functions let you attach generate functions to images  
- * processing operation, and ask for regions of image to be calculated.
+ * 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
+ * For images created with vips_image_new(), vips_image_generate() just 
- * start/generate/stop callbacks and returns.
+ * attaches the start/generate/stop callbacks and returns.
  *
- * For "t" images, memory is allocated for the whole image and it is entirely
+ * For images created with vips_image_new_memory(), memory is allocated for 
- * generated using vips_sink().
+ * 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.
  *

libvips/iofuncs/header.c

@@ -71,41 +71,22 @@
  * SECTION: header
  * @short_description: get, set and walk image headers
  * @stability: Stable
- * @see_also: <link linkend="libvips-meta">meta</link>,
+ * @see_also: <link linkend="libvips-type">type</link>
- * <link linkend="libvips-check">check</link>
  * @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
+ * uniform way. 
- * users.
  *
- * They first search the 
- * VIPS header
- * fields (see <link linkend="libvips-image">image</link>), then search for 
- * a metadata field of that name (see
- * <link linkend="libvips-meta">meta</link>).
  * Use vips_image_get_typeof() to test for the 
  * existance and #GType
  * of a header field.
  *
- * See <link linkend="libvips-meta">meta</link>
+ * You can attach arbitrary metadata to images. Metadata is copied as images
- * 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: <link linkend="libvips-header">header</link>
- * @include: vips/vips.h
- *
- * You can attach arbitrary metadata to images. VipsMetadata 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
+ * immutable. Metadata is handy for things like ICC profiles or EXIF data.
- * 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 
+ * VIPS defines a new %GValue called `vips_save_string`, a variety of string,
- * your GValue can be transformed to vips_save_string, it will be saved and
+ * see vips_value_set_save_string(). 
- * loaded to and from VIPS files for you.
+ * 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
+ * Return the #VipsInterpretation for an image, guessing a sane value if
- * the set value looks wrong.
+ * 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_init (&value, G_TYPE_INT);
- * g_value_set_int( &value, 42 );
+ * g_value_set_int (&value, 42);
- * vips_image_set( image, field, &value );
+ * vips_image_set (image, field, &value);
- * g_value_unset( &value );
+ * g_value_unset (&value);
- *
- * return( 0 );
  * ]|
  *
  * 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
+ * existence of a field first if you are not certain it will be there.
- * 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 ) )
+ * if (vips_image_get (image, field, &value))
- *   return( -1 );
+ *   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_type_name (G_VALUE_TYPE (&value)));
- *   g_value_unset( &value );
+ *   g_value_unset (&value);
- *   return( -1 );
+ *   return -1;
  * }
  *
- * d = g_value_get_double( &value );
+ * d = g_value_get_double (&value);
- * g_value_unset( &value );
+ * g_value_unset (&value);
- *
- * return( 0 );
  * ]|
  *
  * 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", 
+ * vips_image_history_printf (image, "vips invert %s %s", 
- *   in->filename, out->filename );
+ *   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
+ * "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n"
- * 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 )

libvips/iofuncs/image.c

@@ -58,7 +58,10 @@
  * SECTION: image
  * @short_description: the VIPS image class
  * @stability: Stable
- * @see_also: <link linkend="libvips-region">region</link>
+ * @see_also: <link linkend="libvips-header">header</link> 
+ * <link linkend="VipsRegion">VipsRegion</link> 
+ * <link linkend="libvips-generate">generate</link>
+ * <link linkend="VipsOperation">VipsOperation</link> 
  * @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 <link linkend="VipsOperation">operation</link> for an introduction to
  * running operations on images, see <link
  * linkend="libvips-header">header</link> 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
+ * See vips_image_pipelinev(). Operations can hint to the VIPS image IO 
- * the kind of demand geometry they prefer. 
+ * 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 <type>unsigned short</type>.
  */
 
@@ -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
+	 * feedback. Beware of updating too frequently: you will usually
-	 * need to be some mechanism to limit update frequency. 
+	 * 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
+	 * The ::written signal is emitted just after an image has been 
-	 * used by things like vips_image_new_mode("x.jpg", "w") to do the 
+	 * written to. It is
-	 * final write of @image. 
+	 * 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 
+ * Write pixels to an image with vips_image_generate() or 
- * vips_image_new_mode() with @mode "p". 
+ * 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
+ * Make a #VipsImage which, when written to, will create a temporary file on
- * destroyed. @format is something like "&percnt;s.v" for a vips file.
+ * disc. The file will be automatically deleted when the image is destroyed. 
+ * @format is something like "&percnt;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.
  */

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 )

libvips/iofuncs/object.c

@@ -105,11 +105,11 @@
  * The stages inside vips_object_build() are:
  *
  * 1. Chain up through the object's @build class methods. At each stage,
- * each object does any initial setup and checking, then chains up to its
+ * each class does any initial setup and checking, then chains up to its
  * superclass.
  *
- * 2. The innermost @build method in #VipsObject itself checks that all input
+ * 2. The innermost @build method inside #VipsObject itself checks that all 
- * arguments have been set and then returns. 
+ * input arguments have been set and then returns. 
  *
  * 3. All object @build methods now finish executing, from innermost to
  * outermost. They know all input arguments have been checked and supplied, so
@@ -120,7 +120,10 @@
  * signal. #VipsObject::postbuild only runs if the object has constructed
  * successfuly.
  *
- * And the stages inside close are:
+ * #VipsOperation has a cache of recent operation objects, see that class for
+ * an explanation of vips_cache_operation_build(). 
+ *
+ * Finally the stages inside close are:
  *
  * 1. #VipsObject::preclose. This is emitted at the start of
  * the #VipsObject dispose. The object is still functioning. 

libvips/iofuncs/region.c

@@ -158,12 +158,14 @@
  * @X: x coordinate
  * @Y: y coordinate
  *
- * This macro returns a pointer to a pixel in a region. The (x, y) coordinates
+ * This macro returns a pointer to a pixel in a region. The (@X, @Y) 
- * need to be within the #VipsRect (@R->valid).
+ * coordinates need to be within the #VipsRect (@R->valid).
  * 
  * If DEBUG is defined, you get a version that checks bounds for you.
  *
- * Returns: The address of pixel (x,y) in the region.
+ * See also: vips_region_prepare().
+ *
+ * Returns: The address of pixel (@X,@Y) in @R.
  */
 
 /**
@@ -172,6 +174,8 @@
  *
  * This macro returns a pointer to the top-left pixel in the #VipsRegion, that 
  * is, the pixel at (@R->valid.left, @R->valid.top).
+ *
+ * See also: vips_region_prepare().
  * 
  * Returns: The address of the top-left pixel in the region.
  */
@@ -1090,11 +1094,10 @@ vips_region_generate( VipsRegion *reg )
  * the calling thread, no new threads are involved, and computation 
  * blocks until the pixels are ready.
  *
- * Use vips_region_prepare_thread() to calculate an area of pixels with many
+ * Use vips_sink_screen() to calculate an area of pixels in the 
- * threads. Use vips_sink_screen() to calculate an area of pixels in the 
  * background.
  *
- * See also: vips_region_prepare_thread(), vips_sink_screen(), 
+ * See also: vips_sink_screen(), 
  * vips_region_prepare_to().
  *
  * Returns: 0 on success, or -1 on error.

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
+ * Loops over an image. @generate_fn is called for every 
- * the @reg argument being a region of pixels for processing. 
+ * 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
+ * Loops over an image. @generate_fn is called for every pixel in 
- * the @reg argument being a region of pixels for processing. vips_sink() is
+ * the image, with
- * used to implement operations like #VipsAvg which have no image output.
+ * 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.

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().
  *

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
+ * Loops over @im, generating it to a memory buffer attached to @im. It is
- * image. 
+ * 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.
  */

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 );

libvips/iofuncs/type.c

@@ -59,10 +59,10 @@
  * SECTION: type
  * @short_description: basic types
  * @stability: Stable
- * @see_also: <link linkend="libvips-operation">operation</link>
+ * @see_also: <link linkend="libvips-header">header</link>
  * @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.
@@ -138,21 +138,6 @@ vips_thing_get_type( void )
 	return( type );
 }
 
-/**
- * SECTION: VipsArea
- * @short_description: an area of memory
- * @stability: Stable
- * @see_also: <link linkend="libvips-meta">header</link>,
- * @include: vips/vips.h
- *
- * A VipsArea wraps a chunk of memory. It adds reference counting and a free
- * function. It also keeps a count and a GType, so the area can be an array.
- *
- * This type is used for things like passing an array of double or an array of
- * VipsObject pointers to operations, and for reference-counted immutable
- * strings. 
- */
-
 static GSList *vips_area_all = NULL;
 
 VipsArea *
@@ -227,8 +212,14 @@ vips_area_unref( VipsArea *area )
  * @free_fn: (scope async): @data will be freed with this function
  * @data: data will be freed with this function
  *
- * An area of memory with a free function. (eg. \0-terminated string, or a 
+ * A VipsArea wraps a chunk of memory. It adds reference counting and a free
- * struct). Inital count == 1, so _unref() after attaching somewhere.
+ * function. It also keeps a count and a %GType, so the area can be an array.
+ *
+ * This type is used for things like passing an array of double or an array of
+ * #VipsObject pointers to operations, and for reference-counted immutable
+ * strings. 
+ *
+ * Inital count == 1, so _unref() after attaching somewhere.
  *
  * See also: vips_area_unref().
  *
@@ -313,7 +304,7 @@ vips_area_new_blob( VipsCallbackFn free_fn, void *data, size_t length )
  * @sizeof_type: sizeof() an element in the array
  * @n: number of elements in the array
  *
- * An area which holds an array of elements of some GType. To set values for
+ * An area which holds an array of elements of some %GType. To set values for
  * the elements, get the pointer and write.
  *
  * See also: vips_area_unref().
@@ -351,7 +342,7 @@ vips_area_free_array_object( GObject **array, VipsArea *area )
  * vips_area_new_array_object:
  * @n: number of elements in the array
  *
- * An area which holds an array of GObjects. See vips_area_new_array(). When
+ * An area which holds an array of %GObjects. See vips_area_new_array(). When
  * the area is freed, each %GObject will be unreffed.
  *
  * See also: vips_area_unref().
@@ -934,7 +925,7 @@ vips_value_set_save_stringf( GValue *value, const char *fmt, ... )
  * @value: %GValue to get from
  * @length: (allow-none): return length here, optionally
  *
- * Get the C string held internally by the GValue.
+ * Get the C string held internally by the %GValue.
  *
  * Returns: (transfer none): The C string held by @value. 
  */
@@ -946,14 +937,14 @@ vips_value_get_ref_string( const GValue *value, size_t *length )
 
 /** 
  * vips_value_set_ref_string:
- * @value: (out): GValue to set
+ * @value: (out): %GValue to set
  * @str: C string to copy into the GValue
  *
  * Copies the C string @str into @value. 
  *
  * vips_ref_string are immutable C strings that are copied between images by
  * copying reference-counted pointers, making the much more efficient than
- * regular GValue strings.
+ * regular %GValue strings.
  *
  * Returns: 0 on success, -1 otherwise.
  */
@@ -1353,7 +1344,7 @@ vips_value_get_array_object( const GValue *value, int *n )
  * @value: (out): %GValue to set
  * @n: the number of elements 
  *
- * Set @value to hold an array of GObject. Pass in the array length in @n. 
+ * Set @value to hold an array of %GObject. Pass in the array length in @n. 
  *
  * See also: vips_array_object_get().
  *

libvips/iofuncs/vips.c

@@ -92,7 +92,7 @@
  * SECTION: vips
  * @short_description: startup, shutdown, version
  * @stability: Stable
- * @see_also: <link linkend="libvips-operation">operation</link>
+ * @see_also: <link linkend="VipsOperation">VipsOperation</link>
  * @include: vips/vips.h
  *
  * Start VIPS up, shut VIPS down, get version information, relocation.