more docs work

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.?
 
 
 

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

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.