diff --git a/libvips/Vips-8.0.metadata b/libvips/Vips-8.0.metadata
index 0128948c..0cdab554 100644
--- a/libvips/Vips-8.0.metadata
+++ b/libvips/Vips-8.0.metadata
@@ -1,7 +1,29 @@
-Object.new_from_string skip
-Object.print_summary_class skip
-ArgumentClass.object_class skip
-class_find skip
-ClassMapFn.cls type="void*"
-ArgumentClassMapFn.object_class type="void*"
+Object.new_from_string.object_class type="GLib.ObjectClass"
+Object.print_summary_class.klass type="GLib.ObjectClass"
+ArgumentClass.object_class type="GLib.ObjectClass"
+class_find type="GLib.ObjectClass"
+ClassMapFn.cls type="GLib.ObjectClass"
+ArgumentClassMapFn.object_class type="GLib.ObjectClass"
 ArgumentTable type="GLib.HashTable<GLib.ParamSpec,Vips.Argument?>"
+
+Image.eval#virtual_method skip
+Image.invalidate#virtual_method skip
+Image.minimise#virtual_method skip
+Image.posteval#virtual_method skip
+Image.preeval#virtual_method skip
+Image.written#virtual_method skip
+Image.memory skip
+Image.matrix_from_array skip
+
+Object.close#virtual_method skip
+Object.postbuild#virtual_method skip
+Object.postclose#virtual_method skip
+Object.preclose#virtual_method skip
+Object.preclose#method name="do_preclose"
+_object_set_member name="set_member" parent="Vips.Object" symbol_type="method" instance_idx=0
+
+cache_* skip=false name="cache_(.+)" parent="Vips.Cache"
+col_* skip=false name="col_(.+)" parent="Vips.ColorUtils"
+tracked_* skip=false name="tracked_(.+)" parent="Vips.Tracked"
+check_* skip=false parent="Vips.Utils"
+value_* skip=false name="value_(.+)" parent="Vips.Value"
diff --git a/libvips/colour/LabQ2sRGB.c b/libvips/colour/LabQ2sRGB.c
index a8d9ed73..33de79c9 100644
--- a/libvips/colour/LabQ2sRGB.c
+++ b/libvips/colour/LabQ2sRGB.c
@@ -211,7 +211,18 @@ vips_col_sRGB2scRGB_16( int r, int g, int b, float *R, float *G, float *B )
  */
 #define SCALE (VIPS_D65_Y0)
 
-/* scRGB to XYZ. 
+/**
+ * vips_col_scRGB2XYZ:
+ * @R: Input scRGB value
+ * @G: Input scRGB value
+ * @B: Input scRGB value
+ * @X: (out): Return XYZ colour
+ * @Y: (out): Return XYZ colour
+ * @Z: (out): Return XYZ colour
+ *
+ * Turn scRGB into XYZ.
+ *
+ * See also: vips_scRGB2XYZ().
  */
 int
 vips_col_scRGB2XYZ( float R, float G, float B, float *X, float *Y, float *Z )
@@ -223,7 +234,18 @@ vips_col_scRGB2XYZ( float R, float G, float B, float *X, float *Y, float *Z )
 	return( 0 );
 }
 
-/* Turn XYZ into scRGB. 
+/**
+ * vips_col_XYZ2scRGB:
+ * @X: Input XYZ value
+ * @Y: Input XYZ value
+ * @Z: Input XYZ value
+ * @R: (out): Return scRGB colour
+ * @G: (out): Return scRGB colour
+ * @B: (out): Return scRGB colour
+ *
+ * Turn XYZ into scRGB.
+ *
+ * See also: vips_XYZ2scRGB().
  */
 int
 vips_col_XYZ2scRGB( float X, float Y, float Z, float *R, float *G, float *B ) 
diff --git a/libvips/colour/XYZ2Lab.c b/libvips/colour/XYZ2Lab.c
index 4770364a..bfb1b38e 100644
--- a/libvips/colour/XYZ2Lab.c
+++ b/libvips/colour/XYZ2Lab.c
@@ -177,9 +177,9 @@ vips_XYZ2Lab_line( VipsColour *colour, VipsPel *out, VipsPel **in, int width )
  * @X: Input CIE XYZ colour
  * @Y: Input CIE XYZ colour
  * @Z: Input CIE XYZ colour
- * @L: Return CIE Lab value
- * @a: Return CIE Lab value
- * @b: Return CIE Lab value
+ * @L: (out): Return CIE Lab value
+ * @a: (out): Return CIE Lab value
+ * @b: (out): Return CIE Lab value
  *
  * Calculate XYZ from Lab, D65.
  * 
diff --git a/libvips/colour/colourspace.c b/libvips/colour/colourspace.c
index 1b05545d..0c94cabe 100644
--- a/libvips/colour/colourspace.c
+++ b/libvips/colour/colourspace.c
@@ -490,7 +490,7 @@ static VipsColourRoute vips_colour_routes[] = {
  */
 
 /**
- * vips_colourspace_issupported:
+ * vips_colourspace_issupported: (method)
  * @image: input image
  *
  * Test if @image is in a colourspace that vips_colourspace() can process. 
diff --git a/libvips/foreign/foreign.c b/libvips/foreign/foreign.c
index 254b3ec2..3c56f869 100644
--- a/libvips/foreign/foreign.c
+++ b/libvips/foreign/foreign.c
@@ -1868,7 +1868,7 @@ vips_foreign_find_save_sub( VipsForeignSaveClass *save_class,
  *
  * See also: vips_foreign_find_save_buffer(), vips_image_write_to_file().
  *
- * Returns: the name of an operation on success, %NULL on error
+ * Returns: (nullable): the name of an operation on success, %NULL on error
  */
 const char *
 vips_foreign_find_save( const char *name )
@@ -1938,7 +1938,7 @@ vips_foreign_get_suffixes_add_cb( VipsForeignSaveClass *save_class,
  *
  * Free the return result with g_strfreev().
  *
- * Returns: (transfer full): all supported file extensions, as a 
+ * Returns: (transfer full) (array): all supported file extensions, as a 
  * %NULL-terminated array. 
  */
 gchar ** 
@@ -2023,7 +2023,7 @@ vips_foreign_find_save_target_sub( VipsForeignSaveClass *save_class,
  *
  * See also: vips_image_write_to_buffer().
  *
- * Returns: the name of an operation on success, %NULL on error
+ * Returns: (nullable): the name of an operation on success, %NULL on error
  */
 const char *
 vips_foreign_find_save_target( const char *name )
@@ -2081,7 +2081,7 @@ vips_foreign_find_save_buffer_sub( VipsForeignSaveClass *save_class,
  *
  * See also: vips_image_write_to_buffer().
  *
- * Returns: the name of an operation on success, %NULL on error
+ * Returns: (nullable): the name of an operation on success, %NULL on error
  */
 const char *
 vips_foreign_find_save_buffer( const char *name )
diff --git a/libvips/include/vips/interpolate.h b/libvips/include/vips/interpolate.h
index 930e400e..2c248103 100644
--- a/libvips/include/vips/interpolate.h
+++ b/libvips/include/vips/interpolate.h
@@ -33,6 +33,11 @@
 #ifndef VIPS_INTERPOLATE_H
 #define VIPS_INTERPOLATE_H
 
+#include <glib.h>
+#include <glib-object.h>
+#include <vips/object.h>
+#include <vips/region.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /*__cplusplus*/
diff --git a/libvips/include/vips/sbuf.h b/libvips/include/vips/sbuf.h
index b52458bb..89d31eb1 100644
--- a/libvips/include/vips/sbuf.h
+++ b/libvips/include/vips/sbuf.h
@@ -33,6 +33,10 @@
 #ifndef VIPS_SBUF_H
 #define VIPS_SBUF_H
 
+#include <glib.h>
+#include <glib-object.h>
+#include <vips/object.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /*__cplusplus*/
diff --git a/libvips/include/vips/semaphore.h b/libvips/include/vips/semaphore.h
index cbef6fca..86b24c45 100644
--- a/libvips/include/vips/semaphore.h
+++ b/libvips/include/vips/semaphore.h
@@ -37,13 +37,14 @@
 #ifndef VIPS_SEMAPHORE_H
 #define VIPS_SEMAPHORE_H
 
+#include <glib.h>
+#include <vips/vips.h>
+#include <vips/thread.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /*__cplusplus*/
 
-#include <vips/vips.h>
-#include <vips/thread.h>
-
 /* Implement our own semaphores.
  */
 typedef struct {
diff --git a/libvips/include/vips/threadpool.h b/libvips/include/vips/threadpool.h
index 78e7f968..02e5199d 100644
--- a/libvips/include/vips/threadpool.h
+++ b/libvips/include/vips/threadpool.h
@@ -39,11 +39,18 @@
 #ifndef VIPS_THREADPOOL_H
 #define VIPS_THREADPOOL_H
 
+#include <glib.h>
+#include <glib-object.h>
+#include <vips/image.h>
+#include <vips/object.h>
+#include <vips/region.h>
+#include <vips/rect.h>
+#include <vips/semaphore.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /*__cplusplus*/
 
-#include <vips/semaphore.h>
 
 /* Per-thread state. Allocate functions can use these members to
  * communicate with work functions.
diff --git a/libvips/include/vips/transform.h b/libvips/include/vips/transform.h
index 7f2ac326..d1684a05 100644
--- a/libvips/include/vips/transform.h
+++ b/libvips/include/vips/transform.h
@@ -31,6 +31,10 @@
 #ifndef VIPS_TRANSFORM_H
 #define VIPS_TRANSFORM_H
 
+#include <glib.h>
+#include <vips/image.h>
+#include <vips/rect.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif /*__cplusplus*/
diff --git a/libvips/iofuncs/header.c b/libvips/iofuncs/header.c
index 407d2761..f1bd137d 100644
--- a/libvips/iofuncs/header.c
+++ b/libvips/iofuncs/header.c
@@ -367,7 +367,7 @@ meta_init( VipsImage *im )
 }
 
 /**
- * vips_image_get_width: (method)
+ * vips_image_get_width:
  * @image: image to get from
  *
  * Returns: the number of pixels across the image.
@@ -379,7 +379,7 @@ vips_image_get_width( const VipsImage *image )
 }
 
 /**
- * vips_image_get_height: (method)
+ * vips_image_get_height:
  * @image: image to get from
  *
  * Returns: the number of pixels down the image.
@@ -391,7 +391,7 @@ vips_image_get_height( const VipsImage *image )
 }
 
 /**
- * vips_image_get_bands: (method)
+ * vips_image_get_bands:
  * @image: image to get from
  *
  * Returns: the number of bands (channels) in the image.
@@ -403,7 +403,7 @@ vips_image_get_bands( const VipsImage *image )
 }
 
 /**
- * vips_image_get_format: (method)
+ * vips_image_get_format:
  * @image: image to get from
  *
  * Returns: the format of each band element.
@@ -456,7 +456,7 @@ vips_image_get_format_max( VipsBandFormat format )
 }
 
 /**
- * vips_image_guess_format: (method)
+ * vips_image_guess_format:
  * @image: image to guess for
  *
  * Return the #VipsBandFormat for an image, guessing a sane value if
@@ -541,7 +541,7 @@ vips_image_guess_format( const VipsImage *image )
 }
 
 /**
- * vips_image_get_coding: (method)
+ * vips_image_get_coding:
  * @image: image to get from
  *
  * Returns: the image coding
@@ -553,7 +553,7 @@ vips_image_get_coding( const VipsImage *image )
 }
 
 /**
- * vips_image_get_interpretation: (method)
+ * vips_image_get_interpretation:
  * @image: image to get from
  *
  * Return the #VipsInterpretation set in the image header.
@@ -601,7 +601,7 @@ vips_image_default_interpretation( const VipsImage *image )
 }
 
 /**
- * vips_image_guess_interpretation: (method)
+ * vips_image_guess_interpretation:
  * @image: image to guess for
  *
  * Return the #VipsInterpretation for an image, guessing a sane value if
@@ -721,7 +721,7 @@ vips_image_guess_interpretation( const VipsImage *image )
 }
 
 /**
- * vips_image_get_xres: (method)
+ * vips_image_get_xres:
  * @image: image to get from
  *
  * Returns: the horizontal image resolution in pixels per millimeter. 
@@ -733,7 +733,7 @@ vips_image_get_xres( const VipsImage *image )
 }
 
 /**
- * vips_image_get_yres: (method)
+ * vips_image_get_yres:
  * @image: image to get from
  *
  * Returns: the vertical image resolution in pixels per millimeter. 
@@ -745,7 +745,7 @@ vips_image_get_yres( const VipsImage *image )
 }
 
 /**
- * vips_image_get_xoffset: (method)
+ * vips_image_get_xoffset:
  * @image: image to get from
  *
  * Returns: the horizontal position of the image origin, in pixels.
@@ -757,7 +757,7 @@ vips_image_get_xoffset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_yoffset: (method)
+ * vips_image_get_yoffset:
  * @image: image to get from
  *
  * Returns: the vertical position of the image origin, in pixels.
@@ -769,7 +769,7 @@ vips_image_get_yoffset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_filename: (method)
+ * vips_image_get_filename:
  * @image: image to get from
  *
  * Returns: the name of the file the image was loaded from, or NULL if there
@@ -782,7 +782,7 @@ vips_image_get_filename( const VipsImage *image )
 }
 
 /**
- * vips_image_get_mode: (method)
+ * vips_image_get_mode:
  * @image: image to get from
  *
  * Image modes are things like `"t"`, meaning a memory buffer, and `"p"`
@@ -797,7 +797,7 @@ vips_image_get_mode( const VipsImage *image )
 }
 
 /**
- * vips_image_get_scale: (method)
+ * vips_image_get_scale:
  * @image: image to get from
  *
  * Matrix images can have an optional `scale` field for use by integer 
@@ -818,7 +818,7 @@ vips_image_get_scale( const VipsImage *image )
 }
 
 /**
- * vips_image_get_offset: (method)
+ * vips_image_get_offset:
  * @image: image to get from
  *
  * Matrix images can have an optional `offset` field for use by integer 
@@ -839,7 +839,7 @@ vips_image_get_offset( const VipsImage *image )
 }
 
 /**
- * vips_image_get_page_height: (method)
+ * vips_image_get_page_height:
  * @image: image to get from
  *
  * Multi-page images can have a page height. Fetch it, and sanity check it. If
@@ -864,7 +864,7 @@ vips_image_get_page_height( VipsImage *image )
 }
 
 /**
- * vips_image_get_n_pages: (method)
+ * vips_image_get_n_pages:
  * @image: image to get from
  *
  * Fetch and sanity-check #VIPS_META_N_PAGES. Default to 1 if not present or
@@ -890,7 +890,7 @@ vips_image_get_n_pages( VipsImage *image )
 }
 
 /**
- * vips_image_get_n_subifds: (method)
+ * vips_image_get_n_subifds:
  * @image: image to get from
  *
  * Fetch and sanity-check #VIPS_META_N_SUBIFDS. Default to 0 if not present or
@@ -913,7 +913,7 @@ vips_image_get_n_subifds( VipsImage *image )
 }
 
 /**
- * vips_image_get_orientation: (method)
+ * vips_image_get_orientation:
  * @image: image to get from
  *
  * Fetch and sanity-check #VIPS_META_ORIENTATION. Default to 1 (no rotate, 
@@ -937,7 +937,7 @@ vips_image_get_orientation( VipsImage *image )
 }
 
 /**
- * vips_image_get_orientation_swap: (method)
+ * vips_image_get_orientation_swap:
  * @image: image to get from
  *
  * Return %TRUE if applying the orientation would swap width and height.
@@ -954,7 +954,7 @@ vips_image_get_orientation_swap( VipsImage *image )
 }
 
 /**
- * vips_image_get_data: (method)
+ * vips_image_get_data:
  * @image: image to get data for
  *
  * Return a pointer to the image's pixel data, if possible. This can involve
@@ -978,7 +978,7 @@ vips_image_get_data( VipsImage *image )
 }
 
 /**
- * vips_image_init_fields: (method)
+ * vips_image_init_fields:
  * @image: image to init
  * @xsize: image width
  * @ysize: image height
@@ -1113,7 +1113,7 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
 }
 
 /** 
- * vips_image_set: (method)
+ * vips_image_set:
  * @image: image to set the metadata on
  * @name: the name to give the metadata
  * @value: the %GValue to copy into the image
@@ -1199,7 +1199,7 @@ vips_set_value_from_pointer( GValue *value, void *data )
 }
 
 /**
- * vips_image_get: (method)
+ * vips_image_get:
  * @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
@@ -1287,7 +1287,7 @@ vips_image_get( const VipsImage *image, const char *name, GValue *value_copy )
 }
 
 /**
- * vips_image_get_typeof: (method)
+ * vips_image_get_typeof:
  * @image: image to test
  * @name: the name to search for
  *
@@ -1331,7 +1331,7 @@ vips_image_get_typeof( const VipsImage *image, const char *name )
 }
 
 /**
- * vips_image_remove: (method)
+ * vips_image_remove:
  * @image: image to test
  * @name: the name to search for
  *
@@ -1388,7 +1388,7 @@ vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a )
 }
 
 /**
- * vips_image_map: (method)
+ * vips_image_map:
  * @image: image to map over
  * @fn: (scope call): function to call for each header field
  * @a: (closure fn): user data for function
@@ -1451,7 +1451,7 @@ add_fields( VipsImage *image, const char *field, GValue *value, void *a )
 }
 
 /**
- * vips_image_get_fields: (method)
+ * vips_image_get_fields:
  * @image: image to get fields from
  *
  * Get a %NULL-terminated array listing all the metadata field names on @image. 
@@ -1480,7 +1480,7 @@ vips_image_get_fields( VipsImage *image )
 }
 
 /**
- * vips_image_set_area: (method)
+ * vips_image_set_area:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @free_fn: (scope async): free function for @data
@@ -1527,7 +1527,7 @@ meta_get_value( const VipsImage *image,
 }
 
 /**
- * vips_image_get_area: (method)
+ * vips_image_get_area:
  * @image: image to get the metadata from
  * @name: metadata name
  * @data: (out): return metadata value
@@ -1557,11 +1557,11 @@ vips_image_get_area( const VipsImage *image,
 }
 
 /** 
- * vips_image_set_blob: (method)
+ * vips_image_set_blob:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @free_fn: (scope async): free function for @data
- * @data: pointer to area of memory
+ * @data: (array length=length) (element-type guint8): pointer to area of memory
  * @length: length of memory area
  *
  * Attaches @blob as a metadata item on @image under the name @name. A 
@@ -1583,10 +1583,10 @@ vips_image_set_blob( VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_set_blob_copy: (method)
+ * vips_image_set_blob_copy:
  * @image: image to attach the metadata to
  * @name: metadata name
- * @data: pointer to area of memory
+ * @data: (array length=length) (element-type guint8): pointer to area of memory
  * @length: length of memory area
  *
  * Attaches @blob as a metadata item on @image under the name @name, taking
@@ -1622,11 +1622,11 @@ vips_image_set_blob_copy( VipsImage *image,
 }
 
 /** 
- * vips_image_get_blob: (method)
+ * vips_image_get_blob:
  * @image: image to get the metadata from
  * @name: metadata name
- * @data: pointer to area of memory
- * @length: return the blob length here, optionally
+ * @data: (out) (array length=length) (element-type guint8): pointer to area of memory
+ * @length: (out): return the blob length here, optionally
  *
  * Gets @blob from @image under the name @name, optionally returns its length in
  * @length. A convenience
@@ -1654,7 +1654,7 @@ vips_image_get_blob( const VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_get_int: (method)
+ * vips_image_get_int:
  * @image: image to get the header field from
  * @name: field name
  * @out: (out): return field value
@@ -1681,7 +1681,7 @@ vips_image_get_int( const VipsImage *image, const char *name, int *out )
 }
 
 /** 
- * vips_image_set_int: (method)
+ * vips_image_set_int:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @i: metadata value
@@ -1704,10 +1704,10 @@ vips_image_set_int( VipsImage *image, const char *name, int i )
 }
 
 /** 
- * vips_image_get_double: (method)
+ * vips_image_get_double:
  * @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
@@ -1731,7 +1731,7 @@ vips_image_get_double( const VipsImage *image, const char *name, double *out )
 }
 
 /** 
- * vips_image_set_double: (method)
+ * vips_image_set_double:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @d: metadata value
@@ -1754,10 +1754,10 @@ vips_image_set_double( VipsImage *image, const char *name, double d )
 }
 
 /** 
- * vips_image_get_string: (method)
+ * vips_image_get_string:
  * @image: image to get the header field from
  * @name: field name
- * @out: (transfer none): return field value
+ * @out: (out) (transfer none): return field value
  *
  * Gets @out from @im under the name @name. 
  * The field must be of type
@@ -1805,7 +1805,7 @@ vips_image_get_string( const VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_set_string: (method)
+ * vips_image_set_string:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @str: metadata value
@@ -1828,10 +1828,10 @@ vips_image_set_string( VipsImage *image, const char *name, const char *str )
 }
 
 /** 
- * vips_image_get_as_string: (method)
+ * vips_image_get_as_string:
  * @image: image to get the header field from
  * @name: field name
- * @out: (transfer full): return field value as string
+ * @out: (out) (transfer full): return field value as string
  *
  * Returns @name from @image in @out. 
  * This function will read any field, returning it as a printable string.
@@ -1876,32 +1876,32 @@ vips_image_get_as_string( const VipsImage *image,
 }
 
 /**
- * vips_image_print_field: (method)
+ * vips_image_print_field:
  * @image: image to get the header field from
- * @name: field name
+ * @field: field name
  *
  * Prints field @name to stdout as ASCII. Handy for debugging. 
  */
 void
-vips_image_print_field( const VipsImage *image, const char *name )
+vips_image_print_field( const VipsImage *image, const char *field )
 {
 	char *str;
 
-	if( vips_image_get_as_string( image, name, &str ) ) {
+	if( vips_image_get_as_string( image, field, &str ) ) {
 		printf( "vips_image_print_field: unable to read field\n" );
 		return;
 	}
 
-	printf( ".%s: %s\n", name, str );
+	printf( ".%s: %s\n", field, str );
 
 	g_free( str ); 
 }
 
 /** 
- * vips_image_get_image: (method)
+ * vips_image_get_image:
  * @image: image to get the metadata from
  * @name: metadata name
- * @out: (transfer full): return metadata value
+ * @out: (out) (transfer full): return metadata value
  *
  * Gets @out from @im under the name @name. 
  * The field must be of type
@@ -1929,7 +1929,7 @@ vips_image_get_image( const VipsImage *image,
 }
 
 /**
- * vips_image_set_image: (method)
+ * vips_image_set_image:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @im: metadata value
@@ -1951,11 +1951,11 @@ vips_image_set_image( VipsImage *image, const char *name, VipsImage *im )
 }
 
 /** 
- * vips_image_get_array_int: (method)
+ * vips_image_get_array_int:
  * @image: image to get the metadata from
  * @name: metadata name
- * @out: (transfer none): return pointer to array
- * @n: (allow-none): return the number of elements here, optionally
+ * @out: (out) (array length=n) (transfer none): return pointer to array
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Gets @out from @im under the name @name. 
  * The field must be of type
@@ -1985,7 +1985,7 @@ vips_image_get_array_int( VipsImage *image, const char *name,
 }
 
 /**
- * vips_image_set_array_int: (method)
+ * vips_image_set_array_int:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @array: (array length=n) (allow-none): array of ints
@@ -2009,11 +2009,11 @@ vips_image_set_array_int( VipsImage *image, const char *name,
 }
 
 /** 
- * vips_image_get_array_double: (method)
+ * vips_image_get_array_double:
  * @image: image to get the metadata from
  * @name: metadata name
- * @out: (transfer none): return pointer to array
- * @n: (allow-none): return the number of elements here, optionally
+ * @out: (out) (array length=n) (transfer none): return pointer to array
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Gets @out from @im under the name @name. 
  * The field must be of type
@@ -2043,7 +2043,7 @@ vips_image_get_array_double( VipsImage *image, const char *name,
 }
 
 /**
- * vips_image_set_array_double: (method)
+ * vips_image_set_array_double:
  * @image: image to attach the metadata to
  * @name: metadata name
  * @array: (array length=n) (allow-none): array of doubles
@@ -2067,7 +2067,7 @@ vips_image_set_array_double( VipsImage *image, const char *name,
 }
 
 /**
- * vips_image_history_printf: (method)
+ * vips_image_history_printf:
  * @image: add history line to this image
  * @format: printf() format string
  * @...: arguments to format string
@@ -2127,7 +2127,7 @@ vips_image_history_printf( VipsImage *image, const char *fmt, ... )
 }
 
 /**
- * vips_image_history_args: (method)
+ * vips_image_history_args:
  * @image: image to attach history line to
  * @name: program name
  * @argc: number of program arguments
@@ -2163,7 +2163,7 @@ vips_image_history_args( VipsImage *image,
 }
 
 /**
- * vips_image_get_history: (method)
+ * vips_image_get_history:
  * @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 a0749662..8c74c7c4 100644
--- a/libvips/iofuncs/image.c
+++ b/libvips/iofuncs/image.c
@@ -1224,7 +1224,7 @@ vips_image_class_init( VipsImageClass *class )
 	/**
 	 * VipsImage::preeval:
 	 * @image: the image to be calculated
-	 * @progress: #VipsProgress for this image
+	 * @progress: (type VipsProgress): #VipsProgress for this image
 	 *
 	 * The ::preeval signal is emitted once before computation of @image
 	 * starts. It's a good place to set up evaluation feedback.
@@ -1244,7 +1244,7 @@ vips_image_class_init( VipsImageClass *class )
 	/**
 	 * VipsImage::eval:
 	 * @image: the image being calculated
-	 * @progress: #VipsProgress for this image
+	 * @progress: (type VipsProgress): #VipsProgress for this image
 	 *
 	 * The ::eval signal is emitted once per work unit (typically a 128 x
 	 * 128 area of pixels) during image computation. 
@@ -1268,7 +1268,7 @@ vips_image_class_init( VipsImageClass *class )
 	/**
 	 * VipsImage::posteval:
 	 * @image: the image that was calculated
-	 * @progress: #VipsProgress for this image
+	 * @progress: (type VipsProgress): #VipsProgress for this image
 	 *
 	 * The ::posteval signal is emitted once at the end of the computation 
 	 * of @image. It's a good place to shut down evaluation feedback.
@@ -1288,7 +1288,7 @@ vips_image_class_init( VipsImageClass *class )
 	/**
 	 * VipsImage::written:
 	 * @image: the image that was calculated
-	 * @result: set to non-zero to indicate error
+	 * @result: (out) (type gint): set to non-zero to indicate error
 	 *
 	 * The ::written signal is emitted just after an image has been 
 	 * written to. It is
@@ -1398,7 +1398,7 @@ vips_image_invalidate_all_cb( VipsImage *image, void *a, void *b )
 }
 
 /**
- * vips_image_invalidate_all: (method)
+ * vips_image_invalidate_all:
  * @image: #VipsImage to invalidate
  *
  * Invalidate all pixel caches on @image and any downstream images, that
@@ -1438,7 +1438,7 @@ vips_image_minimise_all_cb( VipsImage *image, void *a, void *b )
 }
 
 /**
- * vips_image_minimise_all: (method)
+ * vips_image_minimise_all:
  * @image: #VipsImage to minimise
  *
  * Minimise memory use on this image and any upstream images, that is, images
@@ -1462,7 +1462,7 @@ vips_image_minimise_all( VipsImage *image )
 }
 
 /**
- * vips_image_is_sequential: (method)
+ * vips_image_is_sequential:
  * @image: #VipsImage to minimise
  *
  * TRUE if any of the images upstream from @image were opened in sequential
@@ -1599,7 +1599,7 @@ vips_image_posteval( VipsImage *image )
 }
 
 /**
- * vips_image_set_progress: (method)
+ * vips_image_set_progress:
  * @image: image to signal progress on
  * @progress: turn progress reporting on or off
  *
@@ -1622,7 +1622,7 @@ vips_image_set_progress( VipsImage *image, gboolean progress )
 }
 
 /**
- * vips_image_iskilled: (method)
+ * vips_image_iskilled:
  * @image: image to test
  *
  * If @image has been killed (see vips_image_set_kill()), set an error message,
@@ -1659,7 +1659,7 @@ vips_image_iskilled( VipsImage *image )
 }
 
 /**
- * vips_image_set_kill: (method)
+ * vips_image_set_kill:
  * @image: image to test
  * @kill: the kill state
  *
@@ -2468,7 +2468,7 @@ vips_image_new_from_image1( VipsImage *image, double c )
 }
 
 /**
- * vips_image_set_delete_on_close: (method)
+ * vips_image_set_delete_on_close:
  * @image: image to set
  * @delete_on_close: format of file
  *
@@ -2599,7 +2599,7 @@ vips_image_write_gen( VipsRegion *or,
 }
 
 /**
- * vips_image_write: (method)
+ * vips_image_write:
  * @image: image to write
  * @out: (out): write to this image
  *
@@ -2652,7 +2652,7 @@ vips_image_write( VipsImage *image, VipsImage *out )
 }
 
 /**
- * vips_image_write_to_file: (method)
+ * vips_image_write_to_file:
  * @image: image to write
  * @name: write to this file
  * @...: %NULL-terminated list of optional named arguments
@@ -2714,7 +2714,7 @@ vips_image_write_to_file( VipsImage *image, const char *name, ... )
 }
 
 /**
- * vips_image_write_to_buffer: (method)
+ * vips_image_write_to_buffer:
  * @in: image to write
  * @suffix: format to write 
  * @buf: (array length=size) (element-type guint8) (transfer full): return buffer start here
@@ -2806,7 +2806,7 @@ vips_image_write_to_buffer( VipsImage *in,
 }
 
 /**
- * vips_image_write_to_target: (method)
+ * vips_image_write_to_target:
  * @in: image to write
  * @suffix: format to write 
  * @target: target to write to
@@ -2851,7 +2851,7 @@ vips_image_write_to_target( VipsImage *in,
 }
 
 /**
- * vips_image_write_to_memory: (method)
+ * vips_image_write_to_memory:
  * @in: image to write
  * @size: return buffer length here
  *
@@ -2896,7 +2896,7 @@ vips_image_write_to_memory( VipsImage *in, size_t *size_out )
 }
 
 /**
- * vips_image_decode: (method)
+ * vips_image_decode:
  * @in: image to decode
  * @out: (out): write to this image
  *
@@ -2932,7 +2932,7 @@ vips_image_decode( VipsImage *in, VipsImage **out )
 }
 
 /**
- * vips_image_decode_predict: (method)
+ * vips_image_decode_predict:
  * @in: image to decode
  * @bands: (out): predict bands here
  * @format: (out): predict format here
@@ -2971,7 +2971,7 @@ vips_image_decode_predict( VipsImage *in,
 }
 
 /**
- * vips_image_encode: (method)
+ * vips_image_encode:
  * @in: image to encode
  * @out: (out): write to this image
  * @coding: coding to apply
@@ -3003,7 +3003,7 @@ vips_image_encode( VipsImage *in, VipsImage **out, VipsCoding coding )
 }
 
 /**
- * vips_image_isMSBfirst: (method)
+ * vips_image_isMSBfirst:
  * @image: image to test
  *
  * Return %TRUE if @image is in most-significant-
@@ -3020,7 +3020,7 @@ vips_image_isMSBfirst( VipsImage *image )
 }
 
 /**
- * vips_image_isfile: (method)
+ * vips_image_isfile:
  * @image: image to test
  *
  * Return %TRUE if @image represents a file on disc in some way. 
@@ -3048,7 +3048,7 @@ vips_image_isfile( VipsImage *image )
 }
 
 /**
- * vips_image_ispartial: (method)
+ * vips_image_ispartial:
  * @image: image to test
  *
  * Return %TRUE if @im represents a partial image (a delayed calculation).
@@ -3063,7 +3063,7 @@ vips_image_ispartial( VipsImage *image )
 }
 
 /**
- * vips_image_hasalpha: (method)
+ * vips_image_hasalpha:
  * @image: image to check
  *
  * Look at an image's interpretation and see if it has extra alpha bands. For
@@ -3110,7 +3110,7 @@ vips_image_hasalpha( VipsImage *image )
 }
 
 /**
- * vips_image_write_prepare: (method)
+ * vips_image_write_prepare:
  * @image: image to prepare
  *
  * Call this after setting header fields (width, height, and so on) to
@@ -3174,7 +3174,7 @@ vips_image_write_prepare( VipsImage *image )
 }
 
 /**
- * vips_image_write_line: (method)
+ * vips_image_write_line:
  * @image: image to write to
  * @ypos: vertical position of scan-line to write
  * @linebuffer: scanline of pixels
@@ -3310,7 +3310,7 @@ vips_image_rewind_output( VipsImage *image )
 }
 
 /** 
- * vips_image_copy_memory: (method)
+ * vips_image_copy_memory:
  * @image: image to copy to a memory buffer
  *
  * Make an image which is an area of memory. 
@@ -3363,7 +3363,7 @@ vips_image_copy_memory( VipsImage *image )
 }
 
 /**
- * vips_image_wio_input: (method)
+ * vips_image_wio_input:
  * @image: image to transform
  *
  * Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is,
@@ -3539,7 +3539,7 @@ vips__image_wio_output( VipsImage *image )
 }
  
 /**
- * vips_image_inplace: (method)
+ * vips_image_inplace:
  * @image: image to make read-write
  *
  * Gets @image ready for an in-place operation, such as vips_draw_circle().
@@ -3599,7 +3599,7 @@ vips_image_inplace( VipsImage *image )
 }
 
 /**
- * vips_image_pio_input: (method)
+ * vips_image_pio_input:
  * @image: image to check
  *
  * Check that an image is readable with vips_region_prepare() and friends. 
@@ -3675,7 +3675,7 @@ vips_image_pio_input( VipsImage *image )
 }
 
 /**
- * vips_image_pio_output: (method)
+ * vips_image_pio_output:
  * @image: image to check
  *
  * Check that an image is writeable with vips_image_generate(). If it isn't,
diff --git a/libvips/iofuncs/object.c b/libvips/iofuncs/object.c
index 7152537b..cfcfdeb8 100644
--- a/libvips/iofuncs/object.c
+++ b/libvips/iofuncs/object.c
@@ -430,12 +430,12 @@ vips_object_dump( VipsObject *object, VipsBuf *buf )
 }
 
 void
-vips_object_print_summary_class( VipsObjectClass *class )
+vips_object_print_summary_class( VipsObjectClass *klass )
 {
 	char str[2048];
 	VipsBuf buf = VIPS_BUF_STATIC( str );
 
-	vips_object_summary_class( class, &buf );
+	vips_object_summary_class( klass, &buf );
 	printf( "%s\n", vips_buf_all( &buf ) );
 }
 
diff --git a/libvips/iofuncs/rect.c b/libvips/iofuncs/rect.c
index 9038efb9..9ce06459 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: (method)
+ * vips_rect_isempty:
  * @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: (method)
+ * vips_rect_includesrect:
  * @r1: outer rectangle
  * @r2: inner rectangle
  *
@@ -117,7 +117,7 @@ vips_rect_includesrect( const VipsRect *r1, const VipsRect *r2 )
 }
 
 /**
- * vips_rect_equalsrect: (method)
+ * vips_rect_equalsrect:
  * @r1: first rectangle
  * @r2: second rectangle
  *
@@ -133,7 +133,7 @@ vips_rect_equalsrect( const VipsRect *r1, const VipsRect *r2 )
 }
 
 /**
- * vips_rect_overlapsrect: (method)
+ * vips_rect_overlapsrect:
  * @r1: first rectangle
  * @r2: second rectangle
  *
@@ -152,7 +152,7 @@ vips_rect_overlapsrect( const VipsRect *r1, const VipsRect *r2 )
 }
 
 /**
- * vips_rect_marginadjust: (method)
+ * vips_rect_marginadjust:
  * @r: rectangle to adjust
  * @n: enlarge by
  *
@@ -242,7 +242,7 @@ vips_rect_dup( const VipsRect *r )
 }
 
 /**
- * vips_rect_normalise: (method)
+ * vips_rect_normalise:
  * @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 26852399..22a7956b 100644
--- a/libvips/iofuncs/region.c
+++ b/libvips/iofuncs/region.c
@@ -532,7 +532,7 @@ vips_region_new( VipsImage *image )
  */
 
 /**
- * vips_region_buffer: (method)
+ * vips_region_buffer:
  * @reg: region to operate upon
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -601,7 +601,7 @@ vips_region_buffer( VipsRegion *reg, const VipsRect *r )
 }
 
 /**
- * vips_region_image: (method)
+ * vips_region_image:
  * @reg: region to operate upon
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -681,7 +681,7 @@ vips_region_image( VipsRegion *reg, const VipsRect *r )
 }
 
 /**
- * vips_region_region: (method)
+ * vips_region_region:
  * @reg: region to operate upon
  * @dest: region to connect to
  * @r: #VipsRect of pixels you need to be able to address
@@ -816,7 +816,7 @@ vips_region_equalsregion( VipsRegion *reg1, VipsRegion *reg2 )
 }
 
 /**
- * vips_region_position: (method)
+ * vips_region_position:
  * @reg: region to operate upon
  * @x: position to move to
  * @y: position to move to
@@ -900,7 +900,7 @@ vips_region_fill( VipsRegion *reg,
 }
 
 /**
- * vips_region_paint: (method)
+ * vips_region_paint:
  * @reg: region to operate upon
  * @r: area to paint
  * @value: value to paint
@@ -969,7 +969,7 @@ vips_region_paint( VipsRegion *reg, const VipsRect *r, int value )
 }
 
 /**
- * vips_region_paint_pel: (method)
+ * vips_region_paint_pel:
  * @reg: region to operate upon
  * @r: area to paint
  * @ink: value to paint
@@ -1020,7 +1020,7 @@ vips_region_paint_pel( VipsRegion *reg, const VipsRect *r, const VipsPel *ink )
 }
 
 /**
- * vips_region_black: (method)
+ * vips_region_black:
  * @reg: region to operate upon
  *
  * Paints 0 into the valid part of @reg.
@@ -1606,7 +1606,7 @@ vips_region_generate( VipsRegion *reg, void *a )
 }
 
 /** 
- * vips_region_prepare: (method)
+ * vips_region_prepare:
  * @reg: region to prepare
  * @r: #VipsRect of pixels you need to be able to address
  *
@@ -1733,9 +1733,9 @@ vips_region_prepare_to_generate( VipsRegion *reg,
 }
 
 /** 
- * vips_region_prepare_to: (method)
+ * vips_region_prepare_to:
  * @reg: region to prepare
- * @dest: (inout): region to write to
+ * @dest: 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
@@ -1902,7 +1902,7 @@ vips_region_prepare_many( VipsRegion **reg, const VipsRect *r )
 }
 
 /** 
- * vips_region_fetch: (method)
+ * vips_region_fetch:
  * @region: region to fetch pixels from
  * @left: area of pixels to fetch
  * @top: area of pixels to fetch
@@ -1966,7 +1966,7 @@ vips_region_fetch( VipsRegion *region,
 }
 
 /**
- * vips_region_width: (method)
+ * vips_region_width:
  * @region: fetch width from this
  *
  * Returns: Width of the pixels held in region.
@@ -1978,7 +1978,7 @@ vips_region_width( VipsRegion *region )
 }	
 
 /**
- * vips_region_height: (method)
+ * vips_region_height:
  * @region: fetch height from this
  *
  * Returns: Height of the pixels held in region.
@@ -1990,7 +1990,7 @@ vips_region_height( VipsRegion *region )
 }	
 
 /** 
- * vips_region_invalidate: (method)
+ * vips_region_invalidate:
  * @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 0994a900..361942c3 100644
--- a/libvips/iofuncs/reorder.c
+++ b/libvips/iofuncs/reorder.c
@@ -315,7 +315,7 @@ vips__reorder_set_input( VipsImage *image, VipsImage **in )
 /**
  * vips_reorder_prepare_many: (method)
  * @image: the image that's being written
- * @regions: (array) (element-type VipsRegion): the set of regions to prepare
+ * @regions: (array): 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
diff --git a/libvips/iofuncs/type.c b/libvips/iofuncs/type.c
index d8f76f38..bbbe14b2 100644
--- a/libvips/iofuncs/type.c
+++ b/libvips/iofuncs/type.c
@@ -237,7 +237,7 @@ vips_area_unref( VipsArea *area )
 }
 
 /**
- * vips_area_new: (constructor)
+ * vips_area_new:
  * @free_fn: (scope async): @data will be freed with this function
  * @data: data will be freed with this function
  *
@@ -385,7 +385,7 @@ vips_area_new_array_object( int n )
 }
 
 /**
- * vips_area_get_data: (method)
+ * vips_area_get_data:
  * @area: #VipsArea to fetch from
  * @length: (out) (optional): optionally return length in bytes here
  * @n: (out) (optional): optionally return number of elements here
@@ -564,7 +564,7 @@ transform_save_string_ref_string( const GValue *src_value, GValue *dest_value )
  *
  * See also: vips_area_unref().
  *
- * Returns: (transfer full): the new #VipsRefString, or NULL on error.
+ * Returns: (transfer full) (nullable): the new #VipsRefString, or NULL on error.
  */
 VipsRefString *
 vips_ref_string_new( const char *str )
@@ -586,7 +586,7 @@ vips_ref_string_new( const char *str )
 /**
  * vips_ref_string_get:
  * @refstr: the #VipsRefString to fetch from
- * @length: (allow-none): return length here, optionally
+ * @length: (out) (optional): return length here, optionally
  *
  * Get a pointer to the private string inside a refstr. Handy for language
  * bindings. 
@@ -632,7 +632,7 @@ vips_ref_string_get_type( void )
  * @length: number of bytes in @data
  *
  * Like vips_area_new(), but track a length as well. The returned #VipsBlob
- * takes ownership of @data and will free it with @free_fn. Pass NULL for
+ * takes ownership of @data and will free it with @free_fn. Pass %NULL for
  * @free_fn to not transfer ownership.
  *
  * An area of mem with a free func and a length (some sort of binary object,
@@ -700,7 +700,7 @@ vips_blob_get( VipsBlob *blob, size_t *length )
 
 /* vips_blob_set:
  * @blob: #VipsBlob to set
- * @free_fn: (scope async) (allow-none): @data will be freed with this function
+ * @free_fn: (scope async) (nullable): @data will be freed with this function
  * @data: (array length=length) (element-type guint8) (transfer full): data to store
  * @length: number of bytes in @data
  *
@@ -1405,7 +1405,7 @@ vips_array_image_empty( void )
 }
 
 /**
- * vips_array_image_append: (method)
+ * vips_array_image_append:
  * @array: (transfer none): append to this
  * @image: add this
  *
@@ -1445,7 +1445,7 @@ vips_array_image_append( VipsArrayImage *array, VipsImage *image )
 }
 
 /**
- * vips_array_image_get: (method)
+ * vips_array_image_get:
  * @array: the #VipsArrayImage to fetch from
  * @n: length of array
  *
@@ -1509,7 +1509,7 @@ vips_array_image_get_type( void )
 
 /**
  * vips_value_set_area:
- * @value: (out): set this value
+ * @value: set this value
  * @free_fn: (scope async): data will be freed with this function
  * @data: set @value to track this pointer
  *
@@ -1529,7 +1529,7 @@ vips_value_set_area( GValue *value, VipsCallbackFn free_fn, void *data )
 /**
  * vips_value_get_area:
  * @value: get from this value
- * @length: (allow-none): optionally return length here
+ * @length: (out) (optional): optionally return length here
  *
  * Get the pointer from an area. Don't touch count (area is static).
  *
@@ -1605,7 +1605,7 @@ vips_value_set_save_stringf( GValue *value, const char *fmt, ... )
 /** 
  * vips_value_get_ref_string:
  * @value: %GValue to get from
- * @length: (allow-none): return length here, optionally
+ * @length: (out) (optional): return length here, optionally
  *
  * Get the C string held internally by the %GValue.
  *
@@ -1674,7 +1674,7 @@ vips_value_set_blob( GValue *value,
 
 /** 
  * vips_value_set_blob_free:
- * @value: (out): GValue to set
+ * @value: GValue to set
  * @data: pointer to area of memory
  * @length: length of memory area
  *
@@ -1701,7 +1701,7 @@ vips_value_set_blob_free( GValue *value, void *data, size_t length )
 /** 
  * vips_value_get_blob:
  * @value: GValue to set
- * @length: (allow-none): optionally return length of memory area
+ * @length: (out) (optional): optionally return length of memory area
  *
  * Returns the data pointer from a blob. Optionally returns the length too.
  *
@@ -1744,9 +1744,9 @@ vips_value_set_array( GValue *value, int n, GType type, size_t sizeof_type )
 /** 
  * vips_value_get_array:
  * @value: %GValue to get from
- * @n: (allow-none): return the number of elements here, optionally
- * @type: (allow-none): return the type of each element here, optionally
- * @sizeof_type: (allow-none): return the sizeof each element here, optionally
+ * @n: (out) (optional): return the number of elements here, optionally
+ * @type: (out) (optional): return the type of each element here, optionally
+ * @sizeof_type: (out) (optional): return the sizeof each element here, optionally
  *
  * Return the pointer to the array held by @value.
  * Optionally return the other properties of the array in @n, @type,
@@ -1781,14 +1781,14 @@ vips_value_get_array( const GValue *value,
 /** 
  * vips_value_get_array_int:
  * @value: %GValue to get from
- * @n: (allow-none): return the number of elements here, optionally
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Return the start of the array of ints held by @value.
  * optionally return the number of elements in @n.
  *
  * See also: vips_array_int_new().
  *
- * Returns: (transfer none): The array address.
+ * Returns: (transfer none) (array length=n): The array address.
  */
 int *
 vips_value_get_array_int( const GValue *value, int *n )
@@ -1798,7 +1798,7 @@ vips_value_get_array_int( const GValue *value, int *n )
 
 /** 
  * vips_value_set_array_int:
- * @value: (out): %GValue to get from
+ * @value: %GValue to get from
  * @array: (array length=n) (allow-none): array of ints
  * @n: the number of elements 
  *
@@ -1822,14 +1822,14 @@ vips_value_set_array_int( GValue *value, const int *array, int n )
 /** 
  * vips_value_get_array_double:
  * @value: %GValue to get from
- * @n: (allow-none): return the number of elements here, optionally
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Return the start of the array of doubles held by @value.
  * optionally return the number of elements in @n.
  *
  * See also: vips_array_double_new().
  *
- * Returns: (transfer none): The array address.
+ * Returns: (transfer none) (array length=n): The array address.
  */
 double *
 vips_value_get_array_double( const GValue *value, int *n )
@@ -1839,7 +1839,7 @@ vips_value_get_array_double( const GValue *value, int *n )
 
 /** 
  * vips_value_set_array_double:
- * @value: (out): %GValue to get from
+ * @value: %GValue to get from
  * @array: (array length=n) (allow-none): array of doubles
  * @n: the number of elements 
  *
@@ -1863,14 +1863,14 @@ vips_value_set_array_double( GValue *value, const double *array, int n )
 /** 
  * vips_value_get_array_image:
  * @value: %GValue to get from
- * @n: (allow-none): return the number of elements here, optionally
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Return the start of the array of images held by @value.
  * optionally return the number of elements in @n.
  *
  * See also: vips_value_set_array_image().
  *
- * Returns: (transfer none): The array address.
+ * Returns: (transfer none) (array length=n): The array address.
  */
 VipsImage **
 vips_value_get_array_image( const GValue *value, int *n )
@@ -1880,7 +1880,7 @@ vips_value_get_array_image( const GValue *value, int *n )
 
 /** 
  * vips_value_set_array_image:
- * @value: (out): %GValue to get from
+ * @value: %GValue to get from
  * @n: the number of elements 
  *
  * Set @value to hold an array of images. Pass in the array length in @n. 
@@ -1901,14 +1901,14 @@ vips_value_set_array_image( GValue *value, int n )
 /** 
  * vips_value_get_array_object: (skip)
  * @value: %GValue to get from
- * @n: (allow-none): return the number of elements here, optionally
+ * @n: (out) (optional): return the number of elements here, optionally
  *
  * Return the start of the array of %GObject held by @value.
  * Optionally return the number of elements in @n.
  *
  * See also: vips_area_new_array_object().
  *
- * Returns: (transfer none): The array address.
+ * Returns: (transfer none) (array length=n): The array address.
  */
 GObject **
 vips_value_get_array_object( const GValue *value, int *n )