diff --git a/libvips/iofuncs/error.c b/libvips/iofuncs/error.c
index 3ca63d29..8f12013e 100644
--- a/libvips/iofuncs/error.c
+++ b/libvips/iofuncs/error.c
@@ -324,7 +324,7 @@ vips_error_system( int err, const char *domain, const char *fmt, ... )
 
 /**
  * vips_error_g:
- * @error: glib error pointer
+ * @error: (out): glib error pointer
  *
  * This function sets the glib error pointer from the vips error buffer and
  * clears it. It's handy for returning errors to glib functions from vips.
@@ -1188,7 +1188,7 @@ vips_check_hist( const char *domain, VipsImage *im )
  * vips_check_matrix: 
  * @domain: the originating domain for the error message
  * @im: image to check 
- * @out: put image as in-memory doubles here
+ * @out: (out): put image as in-memory doubles here
  *
  * Matrix images must have width and height less than 100000 and have 1 band.
  *
diff --git a/libvips/iofuncs/generate.c b/libvips/iofuncs/generate.c
index de025d64..ca8c8123 100644
--- a/libvips/iofuncs/generate.c
+++ b/libvips/iofuncs/generate.c
@@ -345,9 +345,9 @@ vips__demand_hint_array( VipsImage *image,
 
 /**
  * vips_image_pipeline_array: 
- * @image: output image
+ * @image: (out): output image
  * @hint: demand hint for @image
- * @in: %NULL-terminated array of input images 
+ * @in: (array zero-terminated=1): %NULL-terminated array of input images 
  *
  * Add an image to a pipeline. @image depends on all of the images in @in,
  * @image prefers to supply pixels according to @hint.
diff --git a/libvips/iofuncs/header.c b/libvips/iofuncs/header.c
index ab58e9d8..0f2086a6 100644
--- a/libvips/iofuncs/header.c
+++ b/libvips/iofuncs/header.c
@@ -351,7 +351,7 @@ meta_init( VipsImage *im )
 }
 
 /**
- * vips_image_get_width:
+ * vips_image_get_width: (method)
  * @image: image to get from
  *
  * Returns: the number of pixels across the image.
@@ -363,7 +363,7 @@ vips_image_get_width( const VipsImage *image )
 }
 
 /**
- * vips_image_get_height:
+ * vips_image_get_height: (method)
  * @image: image to get from
  *
  * Returns: the number of pixels down the image.
@@ -375,7 +375,7 @@ vips_image_get_height( const VipsImage *image )
 }
 
 /**
- * vips_image_get_bands:
+ * vips_image_get_bands: (method)
  * @image: image to get from
  *
  * Returns: the number of bands (channels) in the image.
@@ -387,7 +387,7 @@ vips_image_get_bands( const VipsImage *image )
 }
 
 /**
- * vips_image_get_format:
+ * vips_image_get_format: (method)
  * @image: image to get from
  *
  * Returns: the format of each band element.
@@ -399,7 +399,7 @@ vips_image_get_format( const VipsImage *image )
 }
 
 /**
- * vips_image_guess_format:
+ * vips_image_guess_format: (method)
  * @image: image to guess for
  *
  * Return the #VipsBandFormat for an image, guessing a sane value if
@@ -484,7 +484,7 @@ vips_image_guess_format( const VipsImage *image )
 }
 
 /**
- * vips_image_get_coding:
+ * vips_image_get_coding: (method)
  * @image: image to get from
  *
  * Returns: the image coding
@@ -496,7 +496,7 @@ vips_image_get_coding( const VipsImage *image )
 }
 
 /**
- * vips_image_get_interpretation:
+ * vips_image_get_interpretation: (method)
  * @image: image to get from
  *
  * Return the #VipsInterpretation set in the image header.
@@ -532,7 +532,7 @@ vips_image_default_interpretation( const VipsImage *image )
 }
 
 /**
- * vips_image_guess_interpretation:
+ * vips_image_guess_interpretation: (method)
  * @image: image to guess for
  *
  * Return the #VipsInterpretation for an image, guessing a sane value if
@@ -643,7 +643,7 @@ vips_image_guess_interpretation( const VipsImage *image )
 }
 
 /**
- * vips_image_get_xres:
+ * vips_image_get_xres: (method)
  * @image: image to get from
  *
  * Returns: the horizontal image resolution in pixels per millimeter. 
@@ -655,7 +655,7 @@ vips_image_get_xres( const VipsImage *image )
 }
 
 /**
- * vips_image_get_yres:
+ * vips_image_get_yres: (method)
  * @image: image to get from
  *
  * Returns: the vertical image resolution in pixels per millimeter. 
@@ -667,7 +667,7 @@ vips_image_get_yres( const VipsImage *image )
 }
 
 /**
- * vips_image_get_xoffset:
+ * vips_image_get_xoffset: (method)
  * @image: image to get from
  *
  * Returns: the horizontal position of the image origin, in pixels.
@@ -679,7 +679,7 @@ vips_image_get_xoffset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_yoffset:
+ * vips_image_get_yoffset: (method)
  * @image: image to get from
  *
  * Returns: the vertical position of the image origin, in pixels.
@@ -691,7 +691,7 @@ vips_image_get_yoffset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_filename:
+ * vips_image_get_filename: (method)
  * @image: image to get from
  *
  * Returns: the name of the file the image was loaded from. 
@@ -703,7 +703,7 @@ vips_image_get_filename( const VipsImage *image )
 }
 
 /**
- * vips_image_get_mode:
+ * vips_image_get_mode: (method)
  * @image: image to get from
  *
  * Image modes are things like `"t"`, meaning a memory buffer, and `"p"`
@@ -718,7 +718,7 @@ vips_image_get_mode( const VipsImage *image )
 }
 
 /**
- * vips_image_get_scale:
+ * vips_image_get_scale: (method)
  * @image: image to get from
  *
  * Matrix images can have an optional `scale` field for use by integer 
@@ -739,7 +739,7 @@ vips_image_get_scale( const VipsImage *image )
 }
 
 /**
- * vips_image_get_offset:
+ * vips_image_get_offset: (method)
  * @image: image to get from
  *
  * Matrix images can have an optional `offset` field for use by integer 
@@ -760,7 +760,7 @@ vips_image_get_offset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_data:
+ * vips_image_get_data: (method)
  * @image: image to get data for
  *
  * Return a pointer to the image's pixel data, if possible. This can involve
@@ -784,7 +784,7 @@ vips_image_get_data( VipsImage *image )
 }
 
 /**
- * vips_image_init_fields:
+ * vips_image_init_fields: (method)
  * @image: image to init
  * @xsize: image width
  * @ysize: image height
@@ -916,7 +916,7 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
 }
 
 /** 
- * vips_image_set:
+ * vips_image_set: (method)
  * @image: image to set the metadata on
  * @name: the name to give the metadata
  * @value: the %GValue to copy into the image
@@ -982,7 +982,7 @@ vips_set_value_from_pointer( GValue *value, void *data )
 }
 
 /**
- * vips_image_get:
+ * vips_image_get: (method)
  * @image: image to get the field from from
  * @name: the name to fetch
  * @value_copy: (transfer full) (out caller-allocates): the %GValue is copied into this
@@ -1070,7 +1070,7 @@ vips_image_get( const VipsImage *image, const char *name, GValue *value_copy )
 }
 
 /**
- * vips_image_get_typeof:
+ * vips_image_get_typeof: (method)
  * @image: image to test
  * @name: the name to search for
  *
@@ -1114,7 +1114,7 @@ vips_image_get_typeof( const VipsImage *image, const char *name )
 }
 
 /**
- * vips_image_remove:
+ * vips_image_remove: (method)
  * @image: image to test
  * @name: the name to search for
  *
@@ -1142,10 +1142,10 @@ vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a )
 }
 
 /**
- * vips_image_map: 
+ * vips_image_map: (method)
  * @image: image to map over
  * @fn: (scope call): function to call for each header field
- * @a: user data for function
+ * @a: (closure fn): user data for function
  *
  * This function calls @fn for every header field, including every item of 
  * metadata. 
@@ -1205,7 +1205,7 @@ add_fields( VipsImage *image, const char *field, GValue *value, void *a )
 }
 
 /**
- * vips_image_get_fields:
+ * vips_image_get_fields: (method)
  * @image: image to get fields from
  *
  * Get a %NULL-terminated array listing all the metadata field names on @image. 
@@ -1234,7 +1234,7 @@ vips_image_get_fields( VipsImage *image )
 }
 
 /**
- * vips_image_set_area:
+ * vips_image_set_area: (method)
  * @image: image to attach the metadata to
  * @name: metadata name
  * @free_fn: (scope async): free function for @data
@@ -1281,10 +1281,10 @@ meta_get_value( const VipsImage *image,
 }
 
 /**
- * vips_image_get_area:
+ * vips_image_get_area: (method)
  * @image: image to get the metadata from
  * @name: metadata name
- * @data: return metadata value
+ * @data: (out): return metadata value
  *
  * Gets @data from @image under the name @name. A convenience
  * function over vips_image_get(). Use vips_image_get_typeof() to test for
@@ -1310,7 +1310,7 @@ vips_image_get_area( const VipsImage *image, const char *name, void **data )
 }
 
 /** 
- * vips_image_set_blob:
+ * vips_image_set_blob: (method)
  * @image: image to attach the metadata to
  * @name: metadata name
  * @free_fn: (scope async): free function for @data
@@ -1336,7 +1336,7 @@ vips_image_set_blob( VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_get_blob: 
+ * vips_image_get_blob: (method)
  * @image: image to get the metadata from
  * @name: metadata name
  * @data: pointer to area of memory
@@ -1368,10 +1368,10 @@ vips_image_get_blob( const VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_get_int:
+ * vips_image_get_int: (method)
  * @image: image to get the header field from
  * @name: field name
- * @out: return field value
+ * @out: (out): return field value
  *
  * Gets @out from @im under the name @name. 
  * The value will be transformed into
@@ -1395,7 +1395,7 @@ vips_image_get_int( const VipsImage *image, const char *name, int *out )
 }
 
 /** 
- * vips_image_set_int:
+ * vips_image_set_int: (method)
  * @image: image to attach the metadata to
  * @field: metadata name
  * @i: metadata value
@@ -1418,7 +1418,7 @@ vips_image_set_int( VipsImage *image, const char *field, int i )
 }
 
 /** 
- * vips_image_get_double:
+ * vips_image_get_double: (method)
  * @image: image to get the header field from
  * @name: field name
  * @out: return field value
@@ -1445,7 +1445,7 @@ vips_image_get_double( const VipsImage *image, const char *name, double *out )
 }
 
 /** 
- * vips_image_set_double:
+ * vips_image_set_double: (method)
  * @image: image to attach the metadata to
  * @field: metadata name
  * @d: metadata value
@@ -1468,7 +1468,7 @@ vips_image_set_double( VipsImage *image, const char *field, double d )
 }
 
 /** 
- * vips_image_get_string:
+ * vips_image_get_string: (method)
  * @image: image to get the header field from
  * @name: field name
  * @out: (transfer none): return field value
@@ -1511,7 +1511,7 @@ vips_image_get_string( const VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_set_string:
+ * vips_image_set_string: (method)
  * @image: image to attach the metadata to
  * @field: metadata name
  * @str: metadata value
@@ -1534,7 +1534,7 @@ vips_image_set_string( VipsImage *image, const char *field, const char *str )
 }
 
 /** 
- * vips_image_get_as_string:
+ * vips_image_get_as_string: (method)
  * @image: image to get the header field from
  * @field: field name
  * @out: (transfer full): return field value as string
@@ -1582,7 +1582,7 @@ vips_image_get_as_string( const VipsImage *image,
 }
 
 /**
- * vips_image_print_field:
+ * vips_image_print_field: (method)
  * @image: image to get the header field from
  * @field: field name
  *
@@ -1604,7 +1604,7 @@ vips_image_print_field( const VipsImage *image, const char *field )
 }
 
 /**
- * vips_image_history_printf:
+ * vips_image_history_printf: (method)
  * @image: add history line to this image
  * @format: printf() format string
  * @...: arguments to format string
@@ -1664,11 +1664,11 @@ vips_image_history_printf( VipsImage *image, const char *fmt, ... )
 }
 
 /**
- * vips_image_history_args:
+ * vips_image_history_args: (method)
  * @image: image to attach history line to
  * @name: program name
  * @argc: number of program arguments
- * @argv: program arguments
+ * @argv: (array length=argc) (element-type char*): program arguments
  *
  * Formats the name/argv as a single string and calls
  * vips_image_history_printf(). A
@@ -1700,7 +1700,7 @@ vips_image_history_args( VipsImage *image,
 }
 
 /**
- * vips_image_get_history:
+ * vips_image_get_history: (method)
  * @image: get history from here
  *
  * This function reads the image history as a C string. The string is owned
diff --git a/libvips/iofuncs/image.c b/libvips/iofuncs/image.c
index 66a7feee..a5bbd9ba 100644
--- a/libvips/iofuncs/image.c
+++ b/libvips/iofuncs/image.c
@@ -1413,7 +1413,7 @@ vips_image_invalidate_all_cb( VipsImage *image )
 }
 
 /**
- * vips_image_invalidate_all:
+ * vips_image_invalidate_all: (method)
  * @image: #VipsImage to invalidate
  *
  * Invalidate all pixel caches on @image and any downstream images, that
@@ -1453,7 +1453,7 @@ vips_image_minimise_all_cb( VipsImage *image )
 }
 
 /**
- * vips_image_minimise_all:
+ * vips_image_minimise_all: (method)
  * @image: #VipsImage to minimise
  *
  * Minimise memory use on this image and any upstream images, that is, images
@@ -1591,7 +1591,7 @@ vips_image_posteval( VipsImage *image )
 }
 
 /**
- * vips_image_set_progress:
+ * vips_image_set_progress: (method)
  * @image: image to signal progress on
  * @progress: turn progress reporting on or off
  *
@@ -1615,7 +1615,7 @@ vips_image_set_progress( VipsImage *image, gboolean progress )
 
 
 /**
- * vips_image_iskilled:
+ * vips_image_iskilled: (method)
  * @image: image to test
  *
  * If @image has been killed (see vips_image_set_kill()), set an error message,
@@ -1652,7 +1652,7 @@ vips_image_iskilled( VipsImage *image )
 }
 
 /**
- * vips_image_set_kill:
+ * vips_image_set_kill: (method)
  * @image: image to test
  * @kill: the kill state
  *
@@ -1688,7 +1688,7 @@ vips_image_temp_name( void )
 }
 
 /**
- * vips_image_new:
+ * vips_image_new: (constructor)
  *
  * vips_image_new() creates a new, empty #VipsImage. 
  * If you write to one of these images, vips will just attach some callbacks,
@@ -1744,7 +1744,7 @@ vips_image_new_mode( const char *filename, const char *mode )
 }
 
 /**
- * vips_image_new_memory:
+ * vips_image_new_memory: (constructor)
  *
  * vips_image_new_memory() creates a new #VipsImage which, when written to, will
  * create a memory image. 
@@ -1760,7 +1760,7 @@ vips_image_new_memory( void )
 }
 
 /**
- * vips_image_memory:
+ * vips_image_memory: (constructor)
  *
  * A renamed vips_image_new_memory() ... Some gobject binding systems do not 
  * like more than one _new() method.
@@ -1824,7 +1824,7 @@ vips_filename_get_options( const char *vips_filename )
 }
 
 /**
- * vips_image_new_from_file:
+ * vips_image_new_from_file: (constructor)
  * @name: file to open
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -1924,7 +1924,7 @@ vips_image_new_from_file( const char *name, ... )
 }
 
 /**
- * vips_image_new_from_file_RW:
+ * vips_image_new_from_file_RW: (constructor)
  * @filename: filename to open
  *
  * Opens the named file for simultaneous reading and writing. This will only 
@@ -1942,7 +1942,7 @@ vips_image_new_from_file_RW( const char *filename )
 }
 
 /**
- * vips_image_new_from_file_raw:
+ * vips_image_new_from_file_raw: (constructor)
  * @filename: filename to open
  * @xsize: image width
  * @ysize: image height
@@ -1985,9 +1985,9 @@ vips_image_new_from_file_raw( const char *filename,
 }
 
 /**
- * vips_image_new_from_memory:
+ * vips_image_new_from_memory: (constructor)
  * @data: (array length=size) (element-type guint8) (transfer none): start of memory area
- * @size: length of memory area
+ * @size: (type gsize): length of memory area
  * @width: image width
  * @height: image height
  * @bands: image bands (or bytes per pixel)
@@ -2060,9 +2060,9 @@ vips_image_new_from_memory_copy_cb( VipsImage *image, void *data_copy )
 }
 
 /**
- * vips_image_new_from_memory_copy:
+ * vips_image_new_from_memory_copy: (constructor)
  * @data: (array length=size) (element-type guint8) (transfer none): start of memory area
- * @size: length of memory area
+ * @size: (type gsize): length of memory area
  * @width: image width
  * @height: image height
  * @bands: image bands (or bytes per pixel)
@@ -2102,9 +2102,9 @@ vips_image_new_from_memory_copy( const void *data, size_t size,
 }
 
 /**
- * vips_image_new_from_buffer:
+ * vips_image_new_from_buffer: (constructor)
  * @buf: (array length=len) (element-type guint8) (transfer none): image data
- * @len: length of memory buffer
+ * @len: (type gsize): length of memory buffer
  * @option_string: set of extra options as a string
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -2158,7 +2158,7 @@ vips_image_new_from_buffer( const void *buf, size_t len,
 }
 
 /**
- * vips_image_new_matrix:
+ * vips_image_new_matrix: (constructor)
  * @width: image width
  * @height: image height
  *
@@ -2204,7 +2204,7 @@ vips_image_new_matrix( int width, int height )
 }
 
 /**
- * vips_image_new_matrixv:
+ * vips_image_new_matrixv: (constructor)
  * @width: image width
  * @height: image height
  * @...: matrix coefficients
@@ -2238,11 +2238,11 @@ vips_image_new_matrixv( int width, int height, ... )
 }
 
 /**
- * vips_image_new_matrix_from_array:
+ * vips_image_new_matrix_from_array: (constructor)
  * @width: image width
  * @height: image height
  * @array: (array length=size) (transfer none): array of elements
- * @size: number of elements
+ * @size: (type gsize): number of elements
  *
  * A binding-friendly version of vips_image_new_matrixv().
  *
@@ -2276,11 +2276,11 @@ vips_image_new_matrix_from_array( int width, int height,
 }
 
 /**
- * vips_image_matrix_from_array:
+ * vips_image_matrix_from_array: (constructor)
  * @width: image width
  * @height: image height
  * @array: (array length=size) (transfer none): array of elements
- * @size: number of elements
+ * @size: (type gsize): number of elements
  *
  * A renamed vips_image_new_matrix_from_array(). Some gobject bindings do not
  * like more than one _new method.
@@ -2296,7 +2296,7 @@ vips_image_matrix_from_array( int width, int height,
 }
 
 /**
- * vips_image_new_from_image:
+ * vips_image_new_from_image: (constructor)
  * @image: image to copy
  * @c: (array length=n) (transfer none): array of constants
  * @n: number of constants
@@ -2351,7 +2351,7 @@ vips_image_new_from_image( VipsImage *image, const double *c, int n )
 }
 
 /**
- * vips_image_new_from_image1:
+ * vips_image_new_from_image1: (constructor)
  * @image: image to copy
  * @c: constants
  *
@@ -2370,7 +2370,7 @@ vips_image_new_from_image1( VipsImage *image, double c )
 }
 
 /**
- * vips_image_set_delete_on_close:
+ * vips_image_set_delete_on_close: (method)
  * @image: image to set
  * @delete_on_close: format of file
  *
@@ -2435,7 +2435,7 @@ vips_get_disc_threshold( void )
 }
 
 /**
- * vips_image_new_temp_file:
+ * vips_image_new_temp_file: (constructor)
  * @format: format of file
  *
  * Make a #VipsImage which, when written to, will create a temporary file on
@@ -2501,9 +2501,9 @@ vips_image_write_gen( VipsRegion *or,
 }
 
 /**
- * vips_image_write:
+ * vips_image_write: (method)
  * @image: image to write
- * @out: write to this image
+ * @out: (out): write to this image
  *
  * Write @image to @out. Use vips_image_new() and friends to create the
  * #VipsImage you want to write to.
@@ -2540,7 +2540,7 @@ vips_image_write( VipsImage *image, VipsImage *out )
 }
 
 /**
- * vips_image_write_to_file:
+ * vips_image_write_to_file: (method)
  * @image: image to write
  * @name: write to this file
  * @...: %NULL-terminated list of optional named arguments
@@ -2578,11 +2578,11 @@ vips_image_write_to_file( VipsImage *image, const char *name, ... )
 }
 
 /**
- * vips_image_write_to_buffer:
+ * vips_image_write_to_buffer: (method)
  * @in: image to write
  * @suffix: format to write 
  * @buf: (array length=size) (element-type guint8) (transfer full): return buffer start here
- * @size: return buffer length here
+ * @size: (type gsize): return buffer length here
  * @...: %NULL-terminated list of optional named arguments
  *
  * Writes @in to a memory buffer in a format specified by @suffix. 
@@ -2636,7 +2636,7 @@ vips_image_write_to_buffer( VipsImage *in,
 }
 
 /**
- * vips_image_write_to_memory:
+ * vips_image_write_to_memory: (method)
  * @in: image to write
  * @size: return buffer length here
  *
@@ -2681,9 +2681,9 @@ vips_image_write_to_memory( VipsImage *in, size_t *size_out )
 }
 
 /**
- * vips_image_decode:
+ * vips_image_decode: (method)
  * @in: image to decode
- * @out: write to this image
+ * @out: (out): write to this image
  *
  * A convenience function to unpack to a format that we can compute with. 
  * @out.coding is always #VIPS_CODING_NONE. 
@@ -2717,10 +2717,10 @@ vips_image_decode( VipsImage *in, VipsImage **out )
 }
 
 /**
- * vips_image_decode_predict:
+ * vips_image_decode_predict: (method)
  * @in: image to decode
- * @bands: predict bands here
- * @format: predict format here
+ * @bands: (out): predict bands here
+ * @format: (out): predict format here
  *
  * We often need to know what an image will decode to without actually
  * decoding it, for example, in arg checking.
@@ -2756,9 +2756,9 @@ vips_image_decode_predict( VipsImage *in,
 }
 
 /**
- * vips_image_encode:
+ * vips_image_encode: (method)
  * @in: image to encode
- * @out: write to this image
+ * @out: (out): write to this image
  * @coding: coding to apply
  *
  * A convenience function to pack to a coding. The inverse of
@@ -2788,7 +2788,7 @@ vips_image_encode( VipsImage *in, VipsImage **out, VipsCoding coding )
 }
 
 /**
- * vips_image_isMSBfirst:
+ * vips_image_isMSBfirst: (method)
  * @image: image to test
  *
  * Return %TRUE if @image is in most-significant-
@@ -2805,7 +2805,7 @@ vips_image_isMSBfirst( VipsImage *image )
 }
 
 /**
- * vips_image_isfile:
+ * vips_image_isfile: (method)
  * @image: image to test
  *
  * Return %TRUE if @image represents a file on disc in some way. 
@@ -2832,7 +2832,7 @@ gboolean vips_image_isfile( VipsImage *image )
 }
 
 /**
- * vips_image_ispartial:
+ * vips_image_ispartial: (method)
  * @image: image to test
  *
  * Return %TRUE if @im represents a partial image (a delayed calculation).
@@ -2847,7 +2847,7 @@ vips_image_ispartial( VipsImage *image )
 }
 
 /**
- * vips_image_hasalpha:
+ * vips_image_hasalpha: (method)
  * @image: image to check
  *
  * libvips assumes an image has an alpha if it has two bands (ie. it is a
@@ -2865,7 +2865,7 @@ vips_image_hasalpha( VipsImage *image )
 }
 
 /**
- * vips_image_write_prepare:
+ * vips_image_write_prepare: (method)
  * @image: image to prepare
  *
  * Call this after setting header fields (width, height, and so on) to
@@ -2930,7 +2930,7 @@ vips_image_write_prepare( VipsImage *image )
 }
 
 /**
- * vips_image_write_line:
+ * vips_image_write_line: (method)
  * @image: image to write to
  * @ypos: vertical position of scan-line to write
  * @linebuffer: scanline of pixels
@@ -3066,7 +3066,7 @@ vips_image_rewind_output( VipsImage *image )
 }
 
 /** 
- * vips_image_copy_memory:
+ * vips_image_copy_memory: (method)
  * @image: image to copy to a memory buffer
  *
  * Allocate a memory buffer and copy @image to it. This is a thread-safe
@@ -3121,7 +3121,7 @@ vips_image_copy_memory( VipsImage *image )
 }
 
 /**
- * vips_image_wio_input:
+ * vips_image_wio_input: (method)
  * @image: image to transform
  *
  * Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is,
@@ -3296,7 +3296,7 @@ vips__image_wio_output( VipsImage *image )
 }
  
 /**
- * vips_image_inplace:
+ * vips_image_inplace: (method)
  * @image: image to make read-write
  *
  * Gets @image ready for an in-place operation, such as vips_draw_circle().
@@ -3353,7 +3353,7 @@ vips_image_inplace( VipsImage *image )
 }
 
 /**
- * vips_image_pio_input:
+ * vips_image_pio_input: (method)
  * @image: image to check
  *
  * Check that an image is readable with vips_region_prepare() and friends. 
@@ -3430,7 +3430,7 @@ vips_image_pio_input( VipsImage *image )
 }
 
 /**
- * vips_image_pio_output:
+ * vips_image_pio_output: (method)
  * @image: image to check
  *
  * Check that an image is writeable with vips_image_generate(). If it isn't,
diff --git a/libvips/iofuncs/memory.c b/libvips/iofuncs/memory.c
index f70a726d..5d0d92d0 100644
--- a/libvips/iofuncs/memory.c
+++ b/libvips/iofuncs/memory.c
@@ -145,7 +145,7 @@ vips_malloc_cb( VipsObject *object, char *buf )
 
 /**
  * vips_malloc:
- * @object: allocate memory local to this #VipsObject, or %NULL
+ * @object: (nullable): allocate memory local to this #VipsObject, or %NULL
  * @size: number of bytes to allocate
  *
  * g_malloc() local to @object, that is, the memory will be automatically 
@@ -177,7 +177,7 @@ vips_malloc( VipsObject *object, size_t size )
 
 /**
  * vips_strdup:
- * @object: allocate memory local to this #VipsObject, or %NULL
+ * @object: (nullable): allocate memory local to this #VipsObject, or %NULL
  * @str: string to copy
  *
  * g_strdup() a string. When @object is freed, the string will be freed for
diff --git a/libvips/iofuncs/object.c b/libvips/iofuncs/object.c
index 40e1d3b7..3be15459 100644
--- a/libvips/iofuncs/object.c
+++ b/libvips/iofuncs/object.c
@@ -770,7 +770,7 @@ vips_object_get_argument( VipsObject *object, const char *name,
 }
 
 /**
- * vips_object_argument_isset:
+ * vips_object_argument_isset: (method)
  * @object: the object to fetch the args from
  * @name: arg to fetch
  *
@@ -793,7 +793,7 @@ vips_object_argument_isset( VipsObject *object, const char *name )
 }
 
 /**
- * vips_object_get_argument_flags:
+ * vips_object_get_argument_flags: (method)
  * @object: the object to fetch the args from
  * @name: arg to fetch
  *
@@ -816,7 +816,7 @@ vips_object_get_argument_flags( VipsObject *object, const char *name )
 }
 
 /**
- * vips_object_get_argument_priority:
+ * vips_object_get_argument_priority: (method)
  * @object: the object to fetch the args from
  * @name: arg to fetch
  *
diff --git a/libvips/iofuncs/operation.c b/libvips/iofuncs/operation.c
index 95dcefa4..0582808f 100644
--- a/libvips/iofuncs/operation.c
+++ b/libvips/iofuncs/operation.c
@@ -630,7 +630,7 @@ vips_operation_invalidate( VipsOperation *operation )
 }
 
 /**
- * vips_operation_new:
+ * vips_operation_new: (constructor)
  * @name: nickname of operation to create
  *
  * Return a new #VipsOperation with the specified nickname. Useful for
diff --git a/libvips/iofuncs/rect.c b/libvips/iofuncs/rect.c
index a2f4ec15..d77e024d 100644
--- a/libvips/iofuncs/rect.c
+++ b/libvips/iofuncs/rect.c
@@ -85,7 +85,7 @@ vips_rect_includespoint( const VipsRect *r, int x, int y )
 }
 
 /**
- * vips_rect_isempty:
+ * vips_rect_isempty: (method)
  * @r: rectangle to test
  *
  * Is @r empty? ie. zero width or height.
@@ -99,7 +99,7 @@ vips_rect_isempty( const VipsRect *r )
 }
 
 /**
- * vips_rect_includesrect:
+ * vips_rect_includesrect: (method)
  * @r1: outer rectangle
  * @r2: inner rectangle
  *
@@ -117,7 +117,7 @@ vips_rect_includesrect( const VipsRect *r1, const VipsRect *r2 )
 }
 
 /**
- * vips_rect_equalsrect:
+ * vips_rect_equalsrect: (method)
  * @r1: first rectangle
  * @r2: second rectangle
  *
@@ -133,7 +133,7 @@ vips_rect_equalsrect( const VipsRect *r1, const VipsRect *r2 )
 }
 
 /**
- * vips_rect_marginadjust:
+ * vips_rect_marginadjust: (method)
  * @r: rectangle to adjust
  * @n: enlarge by
  *
@@ -152,7 +152,7 @@ vips_rect_marginadjust( VipsRect *r, int n )
  * vips_rect_intersectrect:
  * @r1: input rectangle 1
  * @r2: input rectangle 2
- * @out: output rectangle 
+ * @out: (out): output rectangle 
  *
  * Fill @out with the intersection of @r1 and @r2. @out can equal @r1 or @r2.
  */
@@ -176,7 +176,7 @@ vips_rect_intersectrect( const VipsRect *r1, const VipsRect *r2, VipsRect *out )
  * vips_rect_unionrect:
  * @r1: input rectangle 1
  * @r2: input rectangle 2
- * @out: output rectangle 
+ * @out: (out): output rectangle 
  *
  * Fill @out with the bounding box of @r1 and @r2. @out can equal @r1 or @r2.
  */
@@ -223,7 +223,7 @@ vips_rect_dup( const VipsRect *r )
 }
 
 /**
- * vips_rect_normalise:
+ * vips_rect_normalise: (method)
  * @r: rect to normalise
  *
  * Make sure width and height are >0 by moving the origin and flipping the
diff --git a/libvips/iofuncs/region.c b/libvips/iofuncs/region.c
index 39b4626e..715da41a 100644
--- a/libvips/iofuncs/region.c
+++ b/libvips/iofuncs/region.c
@@ -508,7 +508,7 @@ vips_region_init( VipsRegion *region )
 }
 
 /**
- * vips_region_new:
+ * vips_region_new: (constructor)
  * @image: image to create this region on
  *
  * Create a region. #VipsRegion s start out empty, you need to call 
@@ -553,7 +553,7 @@ vips_region_new( VipsImage *image )
  */
 
 /**
- * vips_region_buffer:
+ * vips_region_buffer: (method)
  * @reg: region to operate upon
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -622,7 +622,7 @@ vips_region_buffer( VipsRegion *reg, VipsRect *r )
 }
 
 /**
- * vips_region_image:
+ * vips_region_image: (method)
  * @reg: region to operate upon
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -709,7 +709,7 @@ vips_region_image( VipsRegion *reg, VipsRect *r )
 }
 
 /**
- * vips_region_region:
+ * vips_region_region: (method)
  * @reg: region to operate upon
  * @dest: region to connect to
  * @r: #VipsRect of pixels you need to be able to address
@@ -845,7 +845,7 @@ vips_region_equalsregion( VipsRegion *reg1, VipsRegion *reg2 )
 }
 
 /**
- * vips_region_position:
+ * vips_region_position: (method)
  * @reg: region to operate upon
  * @x: position to move to
  * @y: position to move to
@@ -928,7 +928,7 @@ vips_region_fill( VipsRegion *reg, VipsRect *r, VipsRegionFillFn fn, void *a )
 }
 
 /**
- * vips_region_paint:
+ * vips_region_paint: (method)
  * @reg: region to operate upon
  * @r: area to paint
  * @value: value to paint
@@ -997,7 +997,7 @@ vips_region_paint( VipsRegion *reg, VipsRect *r, int value )
 }
 
 /**
- * vips_region_paint_pel:
+ * vips_region_paint_pel: (method)
  * @reg: region to operate upon
  * @r: area to paint
  * @ink: value to paint
@@ -1048,7 +1048,7 @@ vips_region_paint_pel( VipsRegion *reg, VipsRect *r, VipsPel *ink )
 }
 
 /**
- * vips_region_black:
+ * vips_region_black: (method)
  * @reg: region to operate upon
  *
  * Paints 0 into the valid part of @reg.
@@ -1064,7 +1064,7 @@ vips_region_black( VipsRegion *reg )
 /**
  * vips_region_copy:
  * @reg: source region 
- * @dest: destination region 
+ * @dest: (inout): destination region 
  * @r: #VipsRect of pixels you need to copy
  * @x: postion of @r in @dest
  * @y: postion of @r in @dest
@@ -1326,7 +1326,7 @@ vips_region_shrink_alpha( VipsRegion *from, VipsRegion *to, VipsRect *target )
 /**
  * vips_region_shrink:
  * @from: source region 
- * @to: destination region 
+ * @to: (inout): destination region 
  * @target: #VipsRect of pixels you need to copy
  *
  * Write the pixels @target in @to from the x2 larger area in @from.
@@ -1387,7 +1387,7 @@ vips_region_generate( VipsRegion *reg )
 }
 
 /** 
- * vips_region_prepare:
+ * vips_region_prepare: (method)
  * @reg: region to prepare
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -1515,9 +1515,9 @@ vips_region_prepare_to_generate( VipsRegion *reg,
 }
 
 /** 
- * vips_region_prepare_to:
+ * vips_region_prepare_to: (method)
  * @reg: region to prepare
- * @dest: region to write to
+ * @dest: (inout): region to write to
  * @r: #VipsRect of pixels you need to be able to address
  * @x: postion of @r in @dest
  * @y: postion of @r in @dest
@@ -1685,7 +1685,7 @@ vips_region_prepare_many( VipsRegion **reg, VipsRect *r )
 }
 
 /** 
- * vips_region_invalidate: 
+ * vips_region_invalidate: (method)
  * @reg: region to invalidate
  *
  * Mark a region as containing invalid pixels. Calling this function means
diff --git a/libvips/iofuncs/reorder.c b/libvips/iofuncs/reorder.c
index 1c1c3096..47759053 100644
--- a/libvips/iofuncs/reorder.c
+++ b/libvips/iofuncs/reorder.c
@@ -313,9 +313,9 @@ vips__reorder_set_input( VipsImage *image, VipsImage **in )
 }
 
 /**
- * vips_reorder_prepare_many:
+ * vips_reorder_prepare_many: (method)
  * @image: the image that's being written
- * @regions: the set of regions to prepare
+ * @regions: (array) (element-type VipsRegion): the set of regions to prepare
  * @r: the #VipsRect to prepare on each region
  *
  * vips_reorder_prepare_many() runs vips_region_prepare() on each region in
@@ -346,7 +346,7 @@ vips_reorder_prepare_many( VipsImage *image, VipsRegion **regions, VipsRect *r )
 }
 
 /**
- * vips_reorder_margin_hint:
+ * vips_reorder_margin_hint: (method)
  * @image: the image to hint on
  * @margin: the size of the margin this operation has added
  *
diff --git a/libvips/iofuncs/sink.c b/libvips/iofuncs/sink.c
index fbff303c..f8e44a46 100644
--- a/libvips/iofuncs/sink.c
+++ b/libvips/iofuncs/sink.c
@@ -325,7 +325,7 @@ vips_sink_base_progress( void *a )
 }
 
 /**
- * vips_sink_tile:
+ * vips_sink_tile: (method)
  * @im: scan over this image
  * @tile_width: tile width
  * @tile_height: tile height
@@ -391,7 +391,7 @@ vips_sink_tile( VipsImage *im,
 }
 
 /**
- * vips_sink:
+ * vips_sink: (method)
  * @im: scan over this image
  * @start_fn: start sequences with this function
  * @generate_fn: generate pixels with this function
diff --git a/libvips/iofuncs/sinkdisc.c b/libvips/iofuncs/sinkdisc.c
index 8ee93272..acf3ff5e 100644
--- a/libvips/iofuncs/sinkdisc.c
+++ b/libvips/iofuncs/sinkdisc.c
@@ -469,10 +469,10 @@ write_free( Write *write )
  */
 
 /**
- * vips_sink_disc:
+ * vips_sink_disc: (method)
  * @im: image to process
- * @write_fn: called for every batch of pixels
- * @a: client data
+ * @write_fn: (scope call): called for every batch of pixels
+ * @a: (closure write_fn): client data
  *
  * vips_sink_disc() loops over @im, top-to-bottom, generating it in sections.
  * As each section is produced, @write_fn is called.
diff --git a/libvips/iofuncs/sinkscreen.c b/libvips/iofuncs/sinkscreen.c
index 35556dbf..82447667 100644
--- a/libvips/iofuncs/sinkscreen.c
+++ b/libvips/iofuncs/sinkscreen.c
@@ -1021,16 +1021,16 @@ vips_sink_screen_init( void )
 }
 
 /**
- * vips_sink_screen:
+ * vips_sink_screen: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: mask image indicating valid pixels
  * @tile_width: tile width
  * @tile_height: tile height
  * @max_tiles: maximum tiles to cache
  * @priority: rendering priority
- * @notify_fn: pixels are ready notification callback
- * @a: client data for callback
+ * @notify_fn: (scope call) (nullable): pixels are ready notification callback
+ * @a: (closure notify_fn) (nullable): client data for callback
  *
  * This operation renders @in in the background, making pixels available on
  * @out as they are calculated. The @notify_fn callback is run every time a new
diff --git a/libvips/iofuncs/threadpool.c b/libvips/iofuncs/threadpool.c
index 149c0de3..8fcaa8b3 100644
--- a/libvips/iofuncs/threadpool.c
+++ b/libvips/iofuncs/threadpool.c
@@ -1024,11 +1024,11 @@ vips__threadpool_init( void )
 }
 
 /**
- * vips_get_tile_size:
+ * vips_get_tile_size: (method)
  * @im: image to guess for
- * @tile_width: return selected tile width 
- * @tile_height: return selected tile height 
- * @n_lines: return buffer height in scanlines
+ * @tile_width: (out): return selected tile width 
+ * @tile_height: (out): return selected tile height 
+ * @n_lines: (out): return buffer height in scanlines
  *
  * Pick a tile size and a buffer height for this image and the current
  * value of vips_concurrency_get(). The buffer height 
diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c
index 53c2ebae..f8a5d6ee 100644
--- a/libvips/iofuncs/type.c
+++ b/libvips/iofuncs/type.c
@@ -221,7 +221,7 @@ vips_area_unref( VipsArea *area )
 }
 
 /**
- * vips_area_new: 
+ * vips_area_new: (constructor)
  * @free_fn: (scope async): @data will be freed with this function
  * @data: data will be freed with this function
  *
@@ -287,7 +287,7 @@ vips__type_leak( void )
 }
 
 /**
- * vips_area_new_array: 
+ * vips_area_new_array:
  * @type: %GType of elements to store
  * @sizeof_type: sizeof() an element in the array
  * @n: number of elements in the array
@@ -328,7 +328,7 @@ vips_area_free_array_object( GObject **array, VipsArea *area )
 }
 
 /**
- * vips_area_new_array_object:
+ * vips_area_new_array_object: (constructor)
  * @n: number of elements in the array
  *
  * An area which holds an array of %GObject s. See vips_area_new_array(). When
@@ -359,12 +359,12 @@ vips_area_new_array_object( int n )
 }
 
 /**
- * vips_area_get_data:
+ * vips_area_get_data: (method)
  * @area: #VipsArea to fetch from
- * @length: (allow-none): optionally return length in bytes here
- * @n: (allow-none): optionally return number of elements here
- * @type: (allow-none): optionally return element type here
- * @sizeof_type: (allow-none): optionally return sizeof() element type here
+ * @length: (optional): optionally return length in bytes here
+ * @n: (optional): optionally return number of elements here
+ * @type: (optional): optionally return element type here
+ * @sizeof_type: (optional): optionally return sizeof() element type here
  *
  * Return the data pointer plus optionally the length in bytes of an area, 
  * the number of elements, the %GType of each element and the sizeof() each
@@ -1107,7 +1107,7 @@ vips_array_double_get_type( void )
 }
 
 /**
- * vips_array_image_new:
+ * vips_array_image_new: (constructor)
  * @array: (array length=n): array of #VipsImage
  * @n: number of images
  *
@@ -1145,7 +1145,7 @@ vips_array_image_new( VipsImage **array, int n )
 }
 
 /**
- * vips_array_image_newv:
+ * vips_array_image_newv: (constructor)
  * @n: number of images
  * @...: list of #VipsImage arguments
  *
@@ -1232,7 +1232,7 @@ vips_array_image_new_from_string( const char *string, VipsAccess access )
 }
 
 /**
- * vips_array_image_empty:
+ * vips_array_image_empty: (constructor)
  *
  * Make an empty image array. 
  * Handy with vips_array_image_add() for bindings
@@ -1249,7 +1249,7 @@ vips_array_image_empty( void )
 }
 
 /**
- * vips_array_image_append:
+ * vips_array_image_append: (method)
  * @array: (transfer none): append to this
  * @image: add this
  *
@@ -1289,7 +1289,7 @@ vips_array_image_append( VipsArrayImage *array, VipsImage *image )
 }
 
 /**
- * vips_array_image_get:
+ * vips_array_image_get: (method)
  * @array: the #VipsArrayImage to fetch from
  * @n: length of array
  *