diff --git a/ChangeLog b/ChangeLog
index b494f5ef..1e9afc3a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -22,6 +22,7 @@
   binding instead
 - better svgload: larger output, handle missing width/height, thanks lovell
 - add vips_composite(): merge an array of images with porter-duff
+- better gobject-introspection annotations, thanks astavale 
 
 29/8/17 started 8.5.9
 - make --fail stop jpeg read on any libjpeg warning, thanks @mceachen
diff --git a/configure.ac b/configure.ac
index e05cd3d3..174b61e9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -60,8 +60,8 @@ GOBJECT_INTROSPECTION_CHECK([1.30.0])
 #
 # build with a glob and a list of files to exclude from scanning
 # see also IGNORE_HFILES in doc/Makefile.am
-introspection_sources=$(cd libvips ; find . -name "*.c")
-filter_list="deprecated "
+introspection_sources=$(cd libvips ; find . -name "*.c"; find . -name "*.cpp")
+filter_list="deprecated introspect.c dummy.c fuzz "
 
 # contains(string, substring)
 #
@@ -101,8 +101,10 @@ headers="\
 	image.h \
 	error.h \
 	foreign.h \
+	freqfilt.h \
 	interpolate.h \
 	header.h \
+	histogram.h \
 	operation.h \
 	enumtypes.h \
 	conversion.h \
@@ -111,8 +113,10 @@ headers="\
 	convolution.h \
 	draw.h \
 	morphology.h \
+	mosaicing.h \
 	type.h \
 	rect.h \
+	resample.h \
 	memory.h \
 	region.h"
 
diff --git a/cplusplus/VImage.cpp b/cplusplus/VImage.cpp
index 93b2e56e..e04be4fa 100644
--- a/cplusplus/VImage.cpp
+++ b/cplusplus/VImage.cpp
@@ -465,8 +465,7 @@ VImage::call_option_string( const char *operation_name,
 		operation_name );
 
 	if( !(operation = vips_operation_new( operation_name )) ) {
-		if( options )
-			delete options;
+		delete options;
 		throw( VError() ); 
 	}
 
diff --git a/libvips/colour/HSV2sRGB.c b/libvips/colour/HSV2sRGB.c
index e9835234..c11639e8 100644
--- a/libvips/colour/HSV2sRGB.c
+++ b/libvips/colour/HSV2sRGB.c
@@ -132,9 +132,9 @@ vips_HSV2sRGB_init( VipsHSV2sRGB *HSV2sRGB )
 }
 
 /**
- * vips_HSV2sRGB:
+ * vips_HSV2sRGB: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert HSV to sRGB.
diff --git a/libvips/colour/LCh2Lab.c b/libvips/colour/LCh2Lab.c
index 8e257b72..9f615cd3 100644
--- a/libvips/colour/LCh2Lab.c
+++ b/libvips/colour/LCh2Lab.c
@@ -136,9 +136,9 @@ vips_LCh2Lab_init( VipsLCh2Lab *LCh2Lab )
 }
 
 /**
- * vips_LCh2Lab:
+ * vips_LCh2Lab: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to Lab.
diff --git a/libvips/colour/LCh2UCS.c b/libvips/colour/LCh2UCS.c
index ffd11511..4fcc8245 100644
--- a/libvips/colour/LCh2UCS.c
+++ b/libvips/colour/LCh2UCS.c
@@ -217,9 +217,9 @@ vips_LCh2CMC_init( VipsLCh2CMC *LCh2CMC )
 }
 
 /**
- * vips_LCh2CMC:
+ * vips_LCh2CMC: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to CMC.
diff --git a/libvips/colour/Lab2LCh.c b/libvips/colour/Lab2LCh.c
index 7deeb621..9dccb587 100644
--- a/libvips/colour/Lab2LCh.c
+++ b/libvips/colour/Lab2LCh.c
@@ -160,9 +160,9 @@ vips_Lab2LCh_init( VipsLab2LCh *Lab2LCh )
 }
 
 /**
- * vips_Lab2LCh:
+ * vips_Lab2LCh: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn Lab to LCh.
diff --git a/libvips/colour/Lab2LabQ.c b/libvips/colour/Lab2LabQ.c
index f8d3df26..f152537e 100644
--- a/libvips/colour/Lab2LabQ.c
+++ b/libvips/colour/Lab2LabQ.c
@@ -156,9 +156,9 @@ vips_Lab2LabQ_init( VipsLab2LabQ *Lab2LabQ )
 }
 
 /**
- * vips_Lab2LabQ:
+ * vips_Lab2LabQ: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a Lab three-band float image to LabQ (#VIPS_CODING_LABQ).
diff --git a/libvips/colour/Lab2LabS.c b/libvips/colour/Lab2LabS.c
index 08ea4096..939e9286 100644
--- a/libvips/colour/Lab2LabS.c
+++ b/libvips/colour/Lab2LabS.c
@@ -98,9 +98,9 @@ vips_Lab2LabS_init( VipsLab2LabS *Lab2LabS )
 }
 
 /**
- * vips_Lab2LabS:
+ * vips_Lab2LabS: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn Lab to LabS, signed 16-bit int fixed point.
diff --git a/libvips/colour/Lab2XYZ.c b/libvips/colour/Lab2XYZ.c
index 417983e7..5e229e41 100644
--- a/libvips/colour/Lab2XYZ.c
+++ b/libvips/colour/Lab2XYZ.c
@@ -192,9 +192,9 @@ vips_Lab2XYZ_init( VipsLab2XYZ *Lab2XYZ )
 }
 
 /**
- * vips_Lab2XYZ:
+ * vips_Lab2XYZ: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
@@ -224,9 +224,9 @@ vips_Lab2XYZ( VipsImage *in, VipsImage **out, ... )
  * @L: Input CIE Lab value
  * @a: Input CIE Lab value
  * @b: Input CIE Lab value
- * @X: Return CIE XYZ colour
- * @Y: Return CIE XYZ colour
- * @Z: Return CIE XYZ colour
+ * @X: (out): Return CIE XYZ colour
+ * @Y: (out): Return CIE XYZ colour
+ * @Z: (out): Return CIE XYZ colour
  *
  * Calculate XYZ from Lab, D65.
  * 
diff --git a/libvips/colour/LabQ2Lab.c b/libvips/colour/LabQ2Lab.c
index 9cb0197f..b29b0c49 100644
--- a/libvips/colour/LabQ2Lab.c
+++ b/libvips/colour/LabQ2Lab.c
@@ -141,9 +141,9 @@ vips_LabQ2Lab_init( VipsLabQ2Lab *LabQ2Lab )
 }
 
 /**
- * vips_LabQ2Lab:
+ * vips_LabQ2Lab: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band float image.
diff --git a/libvips/colour/LabQ2LabS.c b/libvips/colour/LabQ2LabS.c
index 17d93c79..b6a2f635 100644
--- a/libvips/colour/LabQ2LabS.c
+++ b/libvips/colour/LabQ2LabS.c
@@ -121,9 +121,9 @@ vips_LabQ2LabS_init( VipsLabQ2LabS *LabQ2LabS )
 }
 
 /**
- * vips_LabQ2LabS:
+ * vips_LabQ2LabS: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image.
diff --git a/libvips/colour/LabQ2sRGB.c b/libvips/colour/LabQ2sRGB.c
index 28364b44..737b2712 100644
--- a/libvips/colour/LabQ2sRGB.c
+++ b/libvips/colour/LabQ2sRGB.c
@@ -531,9 +531,9 @@ vips_LabQ2sRGB_init( VipsLabQ2sRGB *LabQ2sRGB )
 }
 
 /**
- * vips_LabQ2sRGB:
+ * vips_LabQ2sRGB: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image.
diff --git a/libvips/colour/LabS2Lab.c b/libvips/colour/LabS2Lab.c
index a83113cc..d1cd1fbe 100644
--- a/libvips/colour/LabS2Lab.c
+++ b/libvips/colour/LabS2Lab.c
@@ -96,9 +96,9 @@ vips_LabS2Lab_init( VipsLabS2Lab *LabS2Lab )
 }
 
 /**
- * vips_LabS2Lab:
+ * vips_LabS2Lab: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a LabS three-band signed short image to a three-band float image.
diff --git a/libvips/colour/LabS2LabQ.c b/libvips/colour/LabS2LabQ.c
index 368514a0..c3efef07 100644
--- a/libvips/colour/LabS2LabQ.c
+++ b/libvips/colour/LabS2LabQ.c
@@ -146,9 +146,9 @@ vips_LabS2LabQ_init( VipsLabS2LabQ *LabS2LabQ )
 }
 
 /**
- * vips_LabS2LabQ:
+ * vips_LabS2LabQ: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a LabS three-band signed short image to LabQ
diff --git a/libvips/colour/UCS2LCh.c b/libvips/colour/UCS2LCh.c
index 26adccef..397861a8 100644
--- a/libvips/colour/UCS2LCh.c
+++ b/libvips/colour/UCS2LCh.c
@@ -284,9 +284,9 @@ vips_CMC2LCh_init( VipsCMC2LCh *CMC2LCh )
 }
 
 /**
- * vips_CMC2LCh:
+ * vips_CMC2LCh: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to CMC.
diff --git a/libvips/colour/XYZ2Lab.c b/libvips/colour/XYZ2Lab.c
index 6d96b46a..14a8b488 100644
--- a/libvips/colour/XYZ2Lab.c
+++ b/libvips/colour/XYZ2Lab.c
@@ -245,9 +245,9 @@ vips_XYZ2Lab_init( VipsXYZ2Lab *XYZ2Lab )
 }
 
 /**
- * vips_XYZ2Lab:
+ * vips_XYZ2Lab: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/colour/XYZ2Yxy.c b/libvips/colour/XYZ2Yxy.c
index 49194515..c15c7c1b 100644
--- a/libvips/colour/XYZ2Yxy.c
+++ b/libvips/colour/XYZ2Yxy.c
@@ -103,9 +103,9 @@ vips_XYZ2Yxy_init( VipsXYZ2Yxy *XYZ2Yxy )
 }
 
 /**
- * vips_XYZ2Yxy:
+ * vips_XYZ2Yxy: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to Yxy.
diff --git a/libvips/colour/XYZ2scRGB.c b/libvips/colour/XYZ2scRGB.c
index eccd4c09..671c599c 100644
--- a/libvips/colour/XYZ2scRGB.c
+++ b/libvips/colour/XYZ2scRGB.c
@@ -116,9 +116,9 @@ vips_XYZ2scRGB_init( VipsXYZ2scRGB *XYZ2scRGB )
 }
 
 /**
- * vips_XYZ2scRGB:
+ * vips_XYZ2scRGB: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to scRGB.
diff --git a/libvips/colour/Yxy2XYZ.c b/libvips/colour/Yxy2XYZ.c
index 9289f349..b15e24e3 100644
--- a/libvips/colour/Yxy2XYZ.c
+++ b/libvips/colour/Yxy2XYZ.c
@@ -104,9 +104,9 @@ vips_Yxy2XYZ_init( VipsYxy2XYZ *Yxy2XYZ )
 }
 
 /**
- * vips_Yxy2XYZ:
+ * vips_Yxy2XYZ: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to Yxy.
diff --git a/libvips/colour/colourspace.c b/libvips/colour/colourspace.c
index ef260a86..68767cfd 100644
--- a/libvips/colour/colourspace.c
+++ b/libvips/colour/colourspace.c
@@ -617,9 +617,9 @@ vips_colourspace_init( VipsColourspace *colourspace )
 }
 
 /**
- * vips_colourspace:
+ * vips_colourspace: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @space: convert to this colour space
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/colour/dE76.c b/libvips/colour/dE76.c
index b32595ba..bb1b6edf 100644
--- a/libvips/colour/dE76.c
+++ b/libvips/colour/dE76.c
@@ -127,7 +127,7 @@ vips_dE76_init( VipsdE76 *dE76 )
  * vips_dE76:
  * @left: first input image
  * @right: second input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate dE 76.
diff --git a/libvips/colour/dECMC.c b/libvips/colour/dECMC.c
index 6aa8771f..726353e0 100644
--- a/libvips/colour/dECMC.c
+++ b/libvips/colour/dECMC.c
@@ -75,7 +75,7 @@ vips_dECMC_init( VipsdECMC *dECMC )
  * vips_dECMC:
  * @left: first input image
  * @right: second input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate dE CMC. The input images are transformed to CMC colour space and
diff --git a/libvips/colour/float2rad.c b/libvips/colour/float2rad.c
index 295f285a..11b069d8 100644
--- a/libvips/colour/float2rad.c
+++ b/libvips/colour/float2rad.c
@@ -220,9 +220,9 @@ vips_float2rad_init( VipsFloat2rad *float2rad )
 }
 
 /**
- * vips_float2rad:
+ * vips_float2rad: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a three-band float image to Radiance 32-bit packed format.
diff --git a/libvips/colour/icc_transform.c b/libvips/colour/icc_transform.c
index 0a852d85..ca8a0c6c 100644
--- a/libvips/colour/icc_transform.c
+++ b/libvips/colour/icc_transform.c
@@ -1054,9 +1054,9 @@ vips_icc_transform_init( VipsIccTransform *transform )
 }
 
 /**
- * vips_icc_ac2rc:
+ * vips_icc_ac2rc: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @profile_filename: use this profile
  *
  * Transform an image from absolute to relative colorimetry using the
@@ -1148,9 +1148,9 @@ vips_icc_ac2rc( VipsImage *in, VipsImage **out, const char *profile_filename )
 #endif /*HAVE_LCMS*/
 
 /**
- * vips_icc_import:
+ * vips_icc_import: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
@@ -1191,9 +1191,9 @@ vips_icc_import( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_icc_export:
+ * vips_icc_export: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
@@ -1226,9 +1226,9 @@ vips_icc_export( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_icc_transform:
+ * vips_icc_transform: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @output_profile: get the output profile from here
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/colour/rad2float.c b/libvips/colour/rad2float.c
index a02e94f2..cecbb38c 100644
--- a/libvips/colour/rad2float.c
+++ b/libvips/colour/rad2float.c
@@ -205,9 +205,9 @@ vips_rad2float_init( VipsRad2float *rad2float )
 }
 
 /**
- * vips_rad2float:
+ * vips_rad2float: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a RAD (#VIPS_CODING_RAD) image to a three-band float image.
diff --git a/libvips/colour/sRGB2HSV.c b/libvips/colour/sRGB2HSV.c
index 5dca321c..9368f41d 100644
--- a/libvips/colour/sRGB2HSV.c
+++ b/libvips/colour/sRGB2HSV.c
@@ -153,9 +153,9 @@ vips_sRGB2HSV_init( VipssRGB2HSV *sRGB2HSV )
 }
 
 /**
- * vips_sRGB2HSV:
+ * vips_sRGB2HSV: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert to HSV.
diff --git a/libvips/colour/sRGB2scRGB.c b/libvips/colour/sRGB2scRGB.c
index 24389506..0b0e877e 100644
--- a/libvips/colour/sRGB2scRGB.c
+++ b/libvips/colour/sRGB2scRGB.c
@@ -259,9 +259,9 @@ vips_sRGB2scRGB_init( VipssRGB2scRGB *sRGB2scRGB )
 }
 
 /**
- * vips_sRGB2scRGB:
+ * vips_sRGB2scRGB: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert an sRGB image to scRGB. The input image can be 8 or 16-bit.
diff --git a/libvips/colour/scRGB2BW.c b/libvips/colour/scRGB2BW.c
index a7f6fddd..d378ca06 100644
--- a/libvips/colour/scRGB2BW.c
+++ b/libvips/colour/scRGB2BW.c
@@ -261,9 +261,9 @@ vips_scRGB2BW_init( VipsscRGB2BW *scRGB2BW )
 }
 
 /**
- * vips_scRGB2BW:
+ * vips_scRGB2BW: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/colour/scRGB2XYZ.c b/libvips/colour/scRGB2XYZ.c
index bf3750db..2596524a 100644
--- a/libvips/colour/scRGB2XYZ.c
+++ b/libvips/colour/scRGB2XYZ.c
@@ -101,9 +101,9 @@ vips_scRGB2XYZ_init( VipsscRGB2XYZ *scRGB2XYZ )
 }
 
 /**
- * vips_scRGB2XYZ:
+ * vips_scRGB2XYZ: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to scRGB.
diff --git a/libvips/colour/scRGB2sRGB.c b/libvips/colour/scRGB2sRGB.c
index 6f8534f5..15149405 100644
--- a/libvips/colour/scRGB2sRGB.c
+++ b/libvips/colour/scRGB2sRGB.c
@@ -289,9 +289,9 @@ vips_scRGB2sRGB_init( VipsscRGB2sRGB *scRGB2sRGB )
 }
 
 /**
- * vips_scRGB2sRGB:
+ * vips_scRGB2sRGB: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/arrayjoin.c b/libvips/conversion/arrayjoin.c
index 3b4e60d4..5f140408 100644
--- a/libvips/conversion/arrayjoin.c
+++ b/libvips/conversion/arrayjoin.c
@@ -384,7 +384,7 @@ vips_arrayjoinv( VipsImage **in, VipsImage **out, int n, va_list ap )
 /**
  * vips_arrayjoin:
  * @in: (array length=n) (transfer none): array of input images
- * @out: output image
+ * @out: (out): output image
  * @n: number of input images
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/autorot.c b/libvips/conversion/autorot.c
index c693dbeb..44a37f00 100644
--- a/libvips/conversion/autorot.c
+++ b/libvips/conversion/autorot.c
@@ -125,7 +125,7 @@ vips_autorot_remove_angle_sub( VipsImage *image,
 }
 
 /**
- * vips_autorot_remove_angle:
+ * vips_autorot_remove_angle: (method)
  * @image: image to remove orientation from
  *
  * Remove the orientation tag on @image. Also remove any exif orientation tags. 
@@ -195,9 +195,9 @@ vips_autorot_init( VipsAutorot *autorot )
 }
 
 /**
- * vips_autorot:
+ * vips_autorot: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/bandbool.c b/libvips/conversion/bandbool.c
index d26c5d7d..25e2f440 100644
--- a/libvips/conversion/bandbool.c
+++ b/libvips/conversion/bandbool.c
@@ -239,9 +239,9 @@ vips_bandboolv( VipsImage *in, VipsImage **out,
 }
 
 /**
- * vips_bandbool:
+ * vips_bandbool: (method)
  * @in: left-hand input #VipsImage
- * @out: output #VipsImage
+ * @out: (out): output #VipsImage
  * @boolean: boolean operation to perform
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -279,9 +279,9 @@ vips_bandbool( VipsImage *in, VipsImage **out,
 }
 
 /**
- * vips_bandand:
+ * vips_bandand: (method)
  * @in: left-hand input #VipsImage
- * @out: output #VipsImage
+ * @out: (out): output #VipsImage
  * @...: %NULL-terminated list of optional named arguments
  *
  * Perform #VIPS_OPERATION_BOOLEAN_AND on an image. See
@@ -303,9 +303,9 @@ vips_bandand( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_bandor:
+ * vips_bandor: (method)
  * @in: left-hand input #VipsImage
- * @out: output #VipsImage
+ * @out: (out): output #VipsImage
  * @...: %NULL-terminated list of optional named arguments
  *
  * Perform #VIPS_OPERATION_BOOLEAN_OR on an image. See
@@ -327,9 +327,9 @@ vips_bandor( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_bandeor:
+ * vips_bandeor: (method)
  * @in: left-hand input #VipsImage
- * @out: output #VipsImage
+ * @out: (out): output #VipsImage
  * @...: %NULL-terminated list of optional named arguments
  *
  * Perform #VIPS_OPERATION_BOOLEAN_EOR on an image. See
diff --git a/libvips/conversion/bandfold.c b/libvips/conversion/bandfold.c
index 9ad72c5e..32e5ecff 100644
--- a/libvips/conversion/bandfold.c
+++ b/libvips/conversion/bandfold.c
@@ -179,9 +179,9 @@ vips_bandfold_init( VipsBandfold *bandfold )
 }
 
 /**
- * vips_bandfold:
+ * vips_bandfold: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/bandjoin.c b/libvips/conversion/bandjoin.c
index f424104d..c47f8a08 100644
--- a/libvips/conversion/bandjoin.c
+++ b/libvips/conversion/bandjoin.c
@@ -204,7 +204,7 @@ vips_bandjoinv( VipsImage **in, VipsImage **out, int n, va_list ap )
 /**
  * vips_bandjoin:
  * @in: (array length=n) (transfer none): array of input images
- * @out: output image
+ * @out: (out): output image
  * @n: number of input images
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -243,7 +243,7 @@ vips_bandjoin( VipsImage **in, VipsImage **out, int n, ... )
  * vips_bandjoin2:
  * @in1: first input image
  * @in2: second input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Join a pair of images together, bandwise. See vips_bandjoin().
@@ -428,9 +428,9 @@ vips_bandjoin_constv( VipsImage *in, VipsImage **out,
 }
 
 /**
- * vips_bandjoin_const:
- * @in: (array length=n) (transfer none): array of input images
- * @out: output image
+ * vips_bandjoin_const: (method)
+ * @in: input image
+ * @out: (out): output image
  * @c: (array length=n): array of constants to append
  * @n: number of constants
  * @...: %NULL-terminated list of optional named arguments
@@ -455,9 +455,9 @@ vips_bandjoin_const( VipsImage *in, VipsImage **out, double *c, int n, ... )
 }
 
 /**
- * vips_bandjoin_const1:
+ * vips_bandjoin_const1: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @c: constant to append
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/bandmean.c b/libvips/conversion/bandmean.c
index 2dd7d01a..f3f057fe 100644
--- a/libvips/conversion/bandmean.c
+++ b/libvips/conversion/bandmean.c
@@ -207,9 +207,9 @@ vips_bandmean_init( VipsBandmean *bandmean )
 }
 
 /**
- * vips_bandmean:
+ * vips_bandmean: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * This operation writes a one-band image where each pixel is the average of 
diff --git a/libvips/conversion/bandrank.c b/libvips/conversion/bandrank.c
index 06ceb969..5256005a 100644
--- a/libvips/conversion/bandrank.c
+++ b/libvips/conversion/bandrank.c
@@ -279,8 +279,8 @@ vips_bandrankv( VipsImage **in, VipsImage **out, int n, va_list ap )
 
 /**
  * vips_bandrank:
- * @in: array of input images
- * @out: output image
+ * @in: (array length=n): array of input images
+ * @out: (out): output image
  * @n: number of input images
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/bandunfold.c b/libvips/conversion/bandunfold.c
index 0aa6064a..c5687f7a 100644
--- a/libvips/conversion/bandunfold.c
+++ b/libvips/conversion/bandunfold.c
@@ -182,9 +182,9 @@ vips_bandunfold_init( VipsBandunfold *bandunfold )
 }
 
 /**
- * vips_bandunfold:
+ * vips_bandunfold: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/byteswap.c b/libvips/conversion/byteswap.c
index be6a834a..c5048fed 100644
--- a/libvips/conversion/byteswap.c
+++ b/libvips/conversion/byteswap.c
@@ -216,9 +216,9 @@ vips_byteswap_init( VipsByteswap *byteswap )
 }
 
 /**
- * vips_byteswap:
+ * vips_byteswap: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Swap the byte order in an image. 
diff --git a/libvips/conversion/cache.c b/libvips/conversion/cache.c
index a7243030..24616cb2 100644
--- a/libvips/conversion/cache.c
+++ b/libvips/conversion/cache.c
@@ -137,9 +137,9 @@ vips_cache_init( VipsCache *cache )
 }
 
 /**
- * vips_cache:
+ * vips_cache: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/cast.c b/libvips/conversion/cast.c
index f984af9e..9f7e9efc 100644
--- a/libvips/conversion/cast.c
+++ b/libvips/conversion/cast.c
@@ -577,9 +577,9 @@ vips_castv( VipsImage *in, VipsImage **out, VipsBandFormat format, va_list ap )
 }
 
 /**
- * vips_cast:
+ * vips_cast: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @format: format to convert to
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -616,9 +616,9 @@ vips_cast( VipsImage *in, VipsImage **out, VipsBandFormat format, ... )
 }
 
 /**
- * vips_cast_uchar:
+ * vips_cast_uchar: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_UCHAR. See vips_cast(). 
@@ -639,9 +639,9 @@ vips_cast_uchar( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_char:
+ * vips_cast_char: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_CHAR. See vips_cast(). 
@@ -662,9 +662,9 @@ vips_cast_char( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_ushort:
+ * vips_cast_ushort: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_USHORT. See vips_cast(). 
@@ -685,9 +685,9 @@ vips_cast_ushort( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_short:
+ * vips_cast_short: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_SHORT. See vips_cast(). 
@@ -708,9 +708,9 @@ vips_cast_short( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_uint:
+ * vips_cast_uint: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_UINT. See vips_cast(). 
@@ -731,9 +731,9 @@ vips_cast_uint( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_int:
+ * vips_cast_int: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_INT. See vips_cast(). 
@@ -754,9 +754,9 @@ vips_cast_int( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_float:
+ * vips_cast_float: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_FLOAT. See vips_cast(). 
@@ -777,9 +777,9 @@ vips_cast_float( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_double:
+ * vips_cast_double: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_DOUBLE. See vips_cast(). 
@@ -800,9 +800,9 @@ vips_cast_double( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_complex:
+ * vips_cast_complex: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_COMPLEX. See vips_cast(). 
@@ -823,9 +823,9 @@ vips_cast_complex( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_cast_dpcomplex:
+ * vips_cast_dpcomplex: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert @in to #VIPS_FORMAT_DPCOMPLEX. See vips_cast(). 
diff --git a/libvips/conversion/copy.c b/libvips/conversion/copy.c
index 5e94a4bf..be621b40 100644
--- a/libvips/conversion/copy.c
+++ b/libvips/conversion/copy.c
@@ -359,9 +359,9 @@ vips_copy_init( VipsCopy *copy )
 }
 
 /**
- * vips_copy:
+ * vips_copy: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
@@ -403,9 +403,9 @@ vips_copy( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_copy_file:
+ * vips_copy_file: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * A simple convenience function to copy an image to a file, then copy 
diff --git a/libvips/conversion/embed.c b/libvips/conversion/embed.c
index 3c20af26..9c064743 100644
--- a/libvips/conversion/embed.c
+++ b/libvips/conversion/embed.c
@@ -618,9 +618,9 @@ vips_embed_init( VipsEmbed *embed )
 }
 
 /**
- * vips_embed:
+ * vips_embed: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @x: place @in at this x position in @out
  * @y: place @in at this y position in @out
  * @width: @out should be this many pixels across
diff --git a/libvips/conversion/extract.c b/libvips/conversion/extract.c
index cee157bf..7448fdd4 100644
--- a/libvips/conversion/extract.c
+++ b/libvips/conversion/extract.c
@@ -232,9 +232,9 @@ vips_extract_area_init( VipsExtractArea *extract )
 }
 
 /**
- * vips_extract_area:
+ * vips_extract_area: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @left: left edge of area to extract
  * @top: top edge of area to extract
  * @width: width of area to extract
@@ -291,9 +291,9 @@ vips_crop_get_type( void )
 }
 
 /**
- * vips_crop:
+ * vips_crop: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @left: left edge of area to extract
  * @top: top edge of area to extract
  * @width: width of area to extract
@@ -442,9 +442,9 @@ vips_extract_band_init( VipsExtractBand *extract )
 }
 
 /**
- * vips_extract_band:
+ * vips_extract_band: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @band: band to extract
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/falsecolour.c b/libvips/conversion/falsecolour.c
index 862799ba..117dad9e 100644
--- a/libvips/conversion/falsecolour.c
+++ b/libvips/conversion/falsecolour.c
@@ -391,9 +391,9 @@ vips_falsecolour_init( VipsFalsecolour *falsecolour )
 }
 
 /**
- * vips_falsecolour:
+ * vips_falsecolour: (method)
  * @in: input image 
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Force @in to 1 band, 8-bit, then transform to 
diff --git a/libvips/conversion/flatten.c b/libvips/conversion/flatten.c
index cfe5fe28..d86975a2 100644
--- a/libvips/conversion/flatten.c
+++ b/libvips/conversion/flatten.c
@@ -412,9 +412,9 @@ vips_flatten_init( VipsFlatten *flatten )
 }
 
 /**
- * vips_flatten:
+ * vips_flatten: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/flip.c b/libvips/conversion/flip.c
index ed70a3c6..550442df 100644
--- a/libvips/conversion/flip.c
+++ b/libvips/conversion/flip.c
@@ -256,9 +256,9 @@ vips_flip_init( VipsFlip *flip )
 }
 
 /**
- * vips_flip:
+ * vips_flip: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @direction: flip horizontally or vertically
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/gamma.c b/libvips/conversion/gamma.c
index 24c07d45..6465b9ae 100644
--- a/libvips/conversion/gamma.c
+++ b/libvips/conversion/gamma.c
@@ -161,9 +161,9 @@ vips_gamma_init( VipsGamma *gamma )
 }
 
 /**
- * vips_gamma:
+ * vips_gamma: (method)
  * @in: input image 
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/grid.c b/libvips/conversion/grid.c
index fd0a2c95..95baf47e 100644
--- a/libvips/conversion/grid.c
+++ b/libvips/conversion/grid.c
@@ -233,9 +233,9 @@ vips_grid_init( VipsGrid *grid )
 }
 
 /**
- * vips_grid:
+ * vips_grid: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @tile_height: chop into tiles this high
  * @across: tiles across
  * @down: tiles down
diff --git a/libvips/conversion/ifthenelse.c b/libvips/conversion/ifthenelse.c
index 38a76bfd..b607da35 100644
--- a/libvips/conversion/ifthenelse.c
+++ b/libvips/conversion/ifthenelse.c
@@ -515,7 +515,7 @@ vips_ifthenelse_init( VipsIfthenelse *ifthenelse )
  * @cond: condition #VipsImage
  * @in1: then #VipsImage
  * @in2: else #VipsImage
- * @out: output #VipsImage
+ * @out: (out): output #VipsImage
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/insert.c b/libvips/conversion/insert.c
index 5f07aff0..01636c51 100644
--- a/libvips/conversion/insert.c
+++ b/libvips/conversion/insert.c
@@ -556,10 +556,10 @@ vips_insert_init( VipsInsert *insert )
 }
 
 /**
- * vips_insert:
+ * vips_insert: (method)
  * @main: big image
  * @sub: small image
- * @out: output image
+ * @out: (out): output image
  * @x: left position of @sub
  * @y: top position of @sub
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/conversion/join.c b/libvips/conversion/join.c
index fc541b46..2219ce5a 100644
--- a/libvips/conversion/join.c
+++ b/libvips/conversion/join.c
@@ -295,7 +295,7 @@ vips_join_init( VipsJoin *join )
  * vips_join:
  * @in1: first input image 
  * @in2: second input image 
- * @out: output image
+ * @out: (out): output image
  * @direction: join horizontally or vertically
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/msb.c b/libvips/conversion/msb.c
index 01e89c9b..a4ced8c7 100644
--- a/libvips/conversion/msb.c
+++ b/libvips/conversion/msb.c
@@ -262,9 +262,9 @@ vips_msb_init( VipsMsb *msb )
 }
 
 /**
- * vips_msb:
+ * vips_msb: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/premultiply.c b/libvips/conversion/premultiply.c
index 24c61522..897c97c3 100644
--- a/libvips/conversion/premultiply.c
+++ b/libvips/conversion/premultiply.c
@@ -276,9 +276,9 @@ vips_premultiply_init( VipsPremultiply *premultiply )
 }
 
 /**
- * vips_premultiply:
+ * vips_premultiply: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/recomb.c b/libvips/conversion/recomb.c
index b6ce8eaf..b24d74d3 100644
--- a/libvips/conversion/recomb.c
+++ b/libvips/conversion/recomb.c
@@ -222,9 +222,9 @@ vips_recomb_init( VipsRecomb *recomb )
 }
 
 /** 
- * vips_recomb:
+ * vips_recomb: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @m: recombination matrix
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/conversion/replicate.c b/libvips/conversion/replicate.c
index a600a0bd..60592fc9 100644
--- a/libvips/conversion/replicate.c
+++ b/libvips/conversion/replicate.c
@@ -220,9 +220,9 @@ vips_replicate_init( VipsReplicate *replicate )
 }
 
 /**
- * vips_replicate:
+ * vips_replicate: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @across: repeat input this many times across
  * @down: repeat input this many times down
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/conversion/rot.c b/libvips/conversion/rot.c
index d07f9e15..2292240c 100644
--- a/libvips/conversion/rot.c
+++ b/libvips/conversion/rot.c
@@ -383,9 +383,9 @@ vips_rotv( VipsImage *in, VipsImage **out, VipsAngle angle, va_list ap )
 }
 
 /**
- * vips_rot:
+ * vips_rot: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @angle: rotation angle
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -437,9 +437,9 @@ vips_rot90( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_rot180:
+ * vips_rot180: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Rotate @in by 180 degress. A convenience function over vips_rot().
@@ -462,9 +462,9 @@ vips_rot180( VipsImage *in, VipsImage **out, ... )
 }
 
 /**
- * vips_rot270:
+ * vips_rot270: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Rotate @in by 270 degress clockwise. A convenience function over vips_rot().
diff --git a/libvips/conversion/rot45.c b/libvips/conversion/rot45.c
index 28bc35a9..c406c429 100644
--- a/libvips/conversion/rot45.c
+++ b/libvips/conversion/rot45.c
@@ -284,9 +284,9 @@ vips_rot45_init( VipsRot45 *rot45 )
 }
 
 /**
- * vips_rot45:
+ * vips_rot45: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/scale.c b/libvips/conversion/scale.c
index 492e80a7..5499eb78 100644
--- a/libvips/conversion/scale.c
+++ b/libvips/conversion/scale.c
@@ -176,9 +176,9 @@ vips_scale_init( VipsScale *scale )
 }
 
 /**
- * vips_scale:
+ * vips_scale: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/sequential.c b/libvips/conversion/sequential.c
index 508269c5..a35d388c 100644
--- a/libvips/conversion/sequential.c
+++ b/libvips/conversion/sequential.c
@@ -265,9 +265,9 @@ vips_sequential_init( VipsSequential *sequential )
 }
 
 /**
- * vips_sequential:
+ * vips_sequential: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/smartcrop.c b/libvips/conversion/smartcrop.c
index f7208519..dd8aa56b 100644
--- a/libvips/conversion/smartcrop.c
+++ b/libvips/conversion/smartcrop.c
@@ -417,9 +417,9 @@ vips_smartcrop_init( VipsSmartcrop *smartcrop )
 }
 
 /**
- * vips_smartcrop:
+ * vips_smartcrop: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @width: width of area to extract
  * @height: height of area to extract
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/conversion/subsample.c b/libvips/conversion/subsample.c
index 9c3d78fa..8a7187eb 100644
--- a/libvips/conversion/subsample.c
+++ b/libvips/conversion/subsample.c
@@ -300,9 +300,9 @@ vips_subsample_init( VipsSubsample *subsample )
 }
 
 /**
- * vips_subsample:
+ * vips_subsample: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @xfac: horizontal shrink factor
  * @yfac: vertical shrink factor
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/conversion/tilecache.c b/libvips/conversion/tilecache.c
index 9d78a726..c1e3722e 100644
--- a/libvips/conversion/tilecache.c
+++ b/libvips/conversion/tilecache.c
@@ -819,9 +819,9 @@ vips_tile_cache_init( VipsTileCache *cache )
 }
 
 /**
- * vips_tilecache:
+ * vips_tilecache: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
@@ -988,9 +988,9 @@ vips_line_cache_init( VipsLineCache *cache )
 }
 
 /**
- * vips_linecache:
+ * vips_linecache: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/unpremultiply.c b/libvips/conversion/unpremultiply.c
index d10c7a40..db118c1a 100644
--- a/libvips/conversion/unpremultiply.c
+++ b/libvips/conversion/unpremultiply.c
@@ -286,9 +286,9 @@ vips_unpremultiply_init( VipsUnpremultiply *unpremultiply )
 }
 
 /**
- * vips_unpremultiply:
+ * vips_unpremultiply: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/wrap.c b/libvips/conversion/wrap.c
index e97ef491..d7e58596 100644
--- a/libvips/conversion/wrap.c
+++ b/libvips/conversion/wrap.c
@@ -143,9 +143,9 @@ vips_wrap_init( VipsWrap *wrap )
 }
 
 /**
- * vips_wrap:
+ * vips_wrap: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/conversion/zoom.c b/libvips/conversion/zoom.c
index 4429b111..e5576f04 100644
--- a/libvips/conversion/zoom.c
+++ b/libvips/conversion/zoom.c
@@ -402,9 +402,9 @@ vips_zoom_init( VipsZoom *zoom )
 }
 
 /**
- * vips_zoom:
+ * vips_zoom: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @xfac: horizontal scale factor
  * @yfac: vertical scale factor
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/convolution/compass.c b/libvips/convolution/compass.c
index 2b9d3861..7e25a3a2 100644
--- a/libvips/convolution/compass.c
+++ b/libvips/convolution/compass.c
@@ -205,9 +205,9 @@ vips_compass_init( VipsCompass *compass )
 }
 
 /**
- * vips_compass:
+ * vips_compass: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/conv.c b/libvips/convolution/conv.c
index 1be0d46f..067ae9f3 100644
--- a/libvips/convolution/conv.c
+++ b/libvips/convolution/conv.c
@@ -167,9 +167,9 @@ vips_conv_init( VipsConv *conv )
 }
 
 /**
- * vips_conv:
+ * vips_conv: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/conva.c b/libvips/convolution/conva.c
index 49aed0aa..e6fd8981 100644
--- a/libvips/convolution/conva.c
+++ b/libvips/convolution/conva.c
@@ -1312,9 +1312,9 @@ vips_conva_init( VipsConva *conva )
 }
 
 /**
- * vips_conva:
+ * vips_conva: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolution mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/convasep.c b/libvips/convolution/convasep.c
index 5534bf52..08e7b468 100644
--- a/libvips/convolution/convasep.c
+++ b/libvips/convolution/convasep.c
@@ -914,9 +914,9 @@ vips_convasep_init( VipsConvasep *convasep )
 }
 
 /**
- * vips_convasep:
+ * vips_convasep: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/convf.c b/libvips/convolution/convf.c
index b420fe21..d6217906 100644
--- a/libvips/convolution/convf.c
+++ b/libvips/convolution/convf.c
@@ -371,9 +371,9 @@ vips_convf_init( VipsConvf *convf )
 }
 
 /**
- * vips_convf:
+ * vips_convf: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/convi.c b/libvips/convolution/convi.c
index 44659f46..aa7b7519 100644
--- a/libvips/convolution/convi.c
+++ b/libvips/convolution/convi.c
@@ -1019,9 +1019,9 @@ vips_convi_init( VipsConvi *convi )
 }
 
 /**
- * vips_convi:
+ * vips_convi: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/convsep.c b/libvips/convolution/convsep.c
index 33f95008..cb1cc178 100644
--- a/libvips/convolution/convsep.c
+++ b/libvips/convolution/convsep.c
@@ -158,9 +158,9 @@ vips_convsep_init( VipsConvsep *convsep )
 }
 
 /**
- * vips_convsep:
+ * vips_convsep: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: convolution mask
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/fastcor.c b/libvips/convolution/fastcor.c
index c9b8dc52..73a557c7 100644
--- a/libvips/convolution/fastcor.c
+++ b/libvips/convolution/fastcor.c
@@ -224,10 +224,10 @@ vips_fastcor_init( VipsFastcor *fastcor )
 }
 
 /**
- * vips_fastcor:
+ * vips_fastcor: (method)
  * @in: input image
  * @ref: reference image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate a fast correlation surface.
diff --git a/libvips/convolution/gaussblur.c b/libvips/convolution/gaussblur.c
index c64833a4..215eefd9 100644
--- a/libvips/convolution/gaussblur.c
+++ b/libvips/convolution/gaussblur.c
@@ -159,9 +159,9 @@ vips_gaussblur_init( VipsGaussblur *gaussblur )
 }
 
 /**
- * vips_gaussblur:
+ * vips_gaussblur: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @sigma: how large a mask to use
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/convolution/sharpen.c b/libvips/convolution/sharpen.c
index 3595852e..f7f91e97 100644
--- a/libvips/convolution/sharpen.c
+++ b/libvips/convolution/sharpen.c
@@ -388,9 +388,9 @@ vips_sharpen_init( VipsSharpen *sharpen )
 }
 
 /**
- * vips_sharpen:
+ * vips_sharpen: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/convolution/spcor.c b/libvips/convolution/spcor.c
index a5134b7f..2d707a99 100644
--- a/libvips/convolution/spcor.c
+++ b/libvips/convolution/spcor.c
@@ -325,10 +325,10 @@ vips_spcor_init( VipsSpcor *spcor )
 }
 
 /**
- * vips_spcor:
+ * vips_spcor: (method)
  * @in: input image
  * @ref: reference image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate a correlation surface.
diff --git a/libvips/draw/draw_circle.c b/libvips/draw/draw_circle.c
index 29a45d94..e0acb69e 100644
--- a/libvips/draw/draw_circle.c
+++ b/libvips/draw/draw_circle.c
@@ -283,7 +283,7 @@ vips_draw_circlev( VipsImage *image,
 }
 
 /**
- * vips_draw_circle:
+ * vips_draw_circle: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: length of ink array
@@ -320,7 +320,7 @@ vips_draw_circle( VipsImage *image,
 }
 
 /**
- * vips_draw_circle1:
+ * vips_draw_circle1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @cx: centre of draw_circle
diff --git a/libvips/draw/draw_flood.c b/libvips/draw/draw_flood.c
index 23f0f2a0..2d2367a1 100644
--- a/libvips/draw/draw_flood.c
+++ b/libvips/draw/draw_flood.c
@@ -678,7 +678,7 @@ vips_draw_floodv( VipsImage *image,
 }
 
 /**
- * vips_draw_flood:
+ * vips_draw_flood: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: length of ink array
@@ -730,7 +730,7 @@ vips_draw_flood( VipsImage *image,
 }
 
 /**
- * vips_draw_flood1:
+ * vips_draw_flood1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @x: centre of circle
diff --git a/libvips/draw/draw_image.c b/libvips/draw/draw_image.c
index 3f9aa053..da0a2c11 100644
--- a/libvips/draw/draw_image.c
+++ b/libvips/draw/draw_image.c
@@ -291,7 +291,7 @@ vips_draw_image_init( VipsDrawImage *draw_image )
 }
 
 /**
- * vips_draw_image:
+ * vips_draw_image: (method)
  * @image: image to draw on
  * @sub: image to paint
  * @x: draw @sub here
diff --git a/libvips/draw/draw_line.c b/libvips/draw/draw_line.c
index a39969cb..30f5ab43 100644
--- a/libvips/draw/draw_line.c
+++ b/libvips/draw/draw_line.c
@@ -331,7 +331,7 @@ vips_draw_linev( VipsImage *image,
 }
 
 /**
- * vips_draw_line:
+ * vips_draw_line: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: length of ink array
@@ -364,7 +364,7 @@ vips_draw_line( VipsImage *image,
 }
 
 /**
- * vips_draw_line1:
+ * vips_draw_line1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @x1: start of draw_line
diff --git a/libvips/draw/draw_mask.c b/libvips/draw/draw_mask.c
index 92228631..24ccf632 100644
--- a/libvips/draw/draw_mask.c
+++ b/libvips/draw/draw_mask.c
@@ -362,7 +362,7 @@ vips_draw_maskv( VipsImage *image,
 }
 
 /**
- * vips_draw_mask:
+ * vips_draw_mask: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: size of ink array
@@ -397,7 +397,7 @@ vips_draw_mask( VipsImage *image,
 }
 
 /**
- * vips_draw_mask1:
+ * vips_draw_mask1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @mask: mask of 0/255 values showing where to plot
diff --git a/libvips/draw/draw_rect.c b/libvips/draw/draw_rect.c
index ac7f33b1..e1599145 100644
--- a/libvips/draw/draw_rect.c
+++ b/libvips/draw/draw_rect.c
@@ -228,7 +228,7 @@ vips_draw_rectv( VipsImage *image,
 }
 
 /**
- * vips_draw_rect:
+ * vips_draw_rect: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: length of ink array
@@ -265,7 +265,7 @@ vips_draw_rect( VipsImage *image,
 }
 
 /**
- * vips_draw_rect1:
+ * vips_draw_rect1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @left: area to paint
@@ -303,7 +303,7 @@ vips_draw_rect1( VipsImage *image,
 }
 
 /**
- * vips_draw_point:
+ * vips_draw_point: (method)
  * @image: image to draw on
  * @ink: (array length=n): value to draw
  * @n: length of ink array
@@ -331,7 +331,7 @@ vips_draw_point( VipsImage *image, double *ink, int n, int x, int y, ... )
 }
 
 /**
- * vips_draw_point1:
+ * vips_draw_point1: (method)
  * @image: image to draw on
  * @ink: value to draw
  * @x: point to draw
diff --git a/libvips/draw/draw_smudge.c b/libvips/draw/draw_smudge.c
index 17f4951e..da4e885f 100644
--- a/libvips/draw/draw_smudge.c
+++ b/libvips/draw/draw_smudge.c
@@ -229,7 +229,7 @@ vips_draw_smudge_init( VipsDrawSmudge *draw_smudge )
 }
 
 /**
- * vips_draw_smudge:
+ * vips_draw_smudge: (method)
  * @image: image to draw on
  * @left: point to paint
  * @top: point to paint
diff --git a/libvips/freqfilt/freqmult.c b/libvips/freqfilt/freqmult.c
index 9e35d882..7775cad2 100644
--- a/libvips/freqfilt/freqmult.c
+++ b/libvips/freqfilt/freqmult.c
@@ -141,10 +141,10 @@ vips_freqmult_init( VipsFreqmult *freqmult )
 }
 
 /**
- * vips_freqmult:
+ * vips_freqmult: (method)
  * @in: input image 
  * @mask: mask image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Multiply @in by @mask in Fourier space.
diff --git a/libvips/freqfilt/fwfft.c b/libvips/freqfilt/fwfft.c
index 4d346358..7217ed5f 100644
--- a/libvips/freqfilt/fwfft.c
+++ b/libvips/freqfilt/fwfft.c
@@ -345,9 +345,9 @@ vips_fwfft_init( VipsFwfft *fwfft )
 #endif /*HAVE_FFTW*/
 
 /**
- * vips_fwfft:
+ * vips_fwfft: (method)
  * @in: input image 
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Transform an image to Fourier space.
diff --git a/libvips/freqfilt/invfft.c b/libvips/freqfilt/invfft.c
index 80ebfa30..16a318fa 100644
--- a/libvips/freqfilt/invfft.c
+++ b/libvips/freqfilt/invfft.c
@@ -269,9 +269,9 @@ vips_invfft_init( VipsInvfft *invfft )
 #endif /*HAVE_FFTW*/
 
 /**
- * vips_invfft:
+ * vips_invfft: (method)
  * @in: input image 
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/freqfilt/phasecor.c b/libvips/freqfilt/phasecor.c
index dad98928..41b36766 100644
--- a/libvips/freqfilt/phasecor.c
+++ b/libvips/freqfilt/phasecor.c
@@ -125,7 +125,7 @@ vips_phasecor_init( VipsPhasecor *phasecor )
  * vips_phasecor:
  * @in1: first input image
  * @in2: second input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Convert the two input images to Fourier space, calculate phase-correlation,
diff --git a/libvips/freqfilt/spectrum.c b/libvips/freqfilt/spectrum.c
index 685c4109..4729e353 100644
--- a/libvips/freqfilt/spectrum.c
+++ b/libvips/freqfilt/spectrum.c
@@ -109,9 +109,9 @@ vips_spectrum_init( VipsSpectrum *spectrum )
 }
 
 /**
- * vips_spectrum:
+ * vips_spectrum: (method)
  * @in: input image 
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Make a displayable (ie. 8-bit unsigned int) power spectrum.
diff --git a/libvips/histogram/hist_cum.c b/libvips/histogram/hist_cum.c
index 57a6cfd2..4f6d7dbe 100644
--- a/libvips/histogram/hist_cum.c
+++ b/libvips/histogram/hist_cum.c
@@ -157,9 +157,9 @@ vips_hist_cum_init( VipsHistCum *hist_cum )
 }
 
 /**
- * vips_hist_cum:
+ * vips_hist_cum: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Form cumulative histogram. 
diff --git a/libvips/histogram/hist_entropy.c b/libvips/histogram/hist_entropy.c
index 582f20a4..373975a2 100644
--- a/libvips/histogram/hist_entropy.c
+++ b/libvips/histogram/hist_entropy.c
@@ -130,9 +130,9 @@ vips_hist_entropy_init( VipsHistEntropy *entropy )
 }
 
 /**
- * vips_hist_entropy:
+ * vips_hist_entropy: (method)
  * @in: input histogram 
- * @out: image entropy
+ * @out: (out): image entropy
  * @...: %NULL-terminated list of optional named arguments
  *
  * Estimate image entropy from a histogram. Entropy is calculated as:
diff --git a/libvips/histogram/hist_equal.c b/libvips/histogram/hist_equal.c
index 159ec543..8cb6dd17 100644
--- a/libvips/histogram/hist_equal.c
+++ b/libvips/histogram/hist_equal.c
@@ -137,9 +137,9 @@ vips_hist_equal_init( VipsHistEqual *equal )
 }
 
 /**
- * vips_hist_equal:
+ * vips_hist_equal: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/histogram/hist_ismonotonic.c b/libvips/histogram/hist_ismonotonic.c
index 9a4b6986..24d85c4c 100644
--- a/libvips/histogram/hist_ismonotonic.c
+++ b/libvips/histogram/hist_ismonotonic.c
@@ -136,9 +136,9 @@ vips_hist_ismonotonic_init( VipsHistIsmonotonic *ismonotonic )
 }
 
 /**
- * vips_hist_ismonotonic:
+ * vips_hist_ismonotonic: (method)
  * @in: lookup-table to test
- * @out: set non-zero if @in is monotonic 
+ * @out: (out): set non-zero if @in is monotonic
  * @...: %NULL-terminated list of optional named arguments
  *
  * Test @in for monotonicity. @out is set non-zero if @in is monotonic.
diff --git a/libvips/histogram/hist_local.c b/libvips/histogram/hist_local.c
index 9d0d36b6..9022ef4e 100644
--- a/libvips/histogram/hist_local.c
+++ b/libvips/histogram/hist_local.c
@@ -395,9 +395,9 @@ vips_hist_local_init( VipsHistLocal *local )
 }
 
 /**
- * vips_hist_local:
+ * vips_hist_local: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @width: width of region
  * @height: height of region
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/histogram/hist_match.c b/libvips/histogram/hist_match.c
index 8f196385..b952d101 100644
--- a/libvips/histogram/hist_match.c
+++ b/libvips/histogram/hist_match.c
@@ -177,10 +177,10 @@ vips_hist_match_init( VipsHistMatch *match )
 }
 
 /**
- * vips_hist_match:
+ * vips_hist_match: (method)
  * @in: input histogram
  * @ref: reference histogram 
- * @out: output histogram
+ * @out: (out): output histogram
  * @...: %NULL-terminated list of optional named arguments
  *
  * Adjust @in to match @ref. If @in and @ref are normalised
diff --git a/libvips/histogram/hist_norm.c b/libvips/histogram/hist_norm.c
index 3baf5c64..b4de016d 100644
--- a/libvips/histogram/hist_norm.c
+++ b/libvips/histogram/hist_norm.c
@@ -156,9 +156,9 @@ vips_hist_norm_init( VipsHistNorm *hist_norm )
 }
 
 /**
- * vips_hist_norm:
+ * vips_hist_norm: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  * 
  * Normalise histogram ... normalise range to make it square (ie. max ==
diff --git a/libvips/histogram/hist_plot.c b/libvips/histogram/hist_plot.c
index 41af74bb..033379b5 100644
--- a/libvips/histogram/hist_plot.c
+++ b/libvips/histogram/hist_plot.c
@@ -357,9 +357,9 @@ vips_hist_plot_init( VipsHistPlot *hist_plot )
 }
 
 /**
- * vips_hist_plot:
+ * vips_hist_plot: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Plot a 1 by any or any by 1 image file as a max by any or 
diff --git a/libvips/histogram/maplut.c b/libvips/histogram/maplut.c
index f1dce435..3d691f21 100644
--- a/libvips/histogram/maplut.c
+++ b/libvips/histogram/maplut.c
@@ -724,9 +724,9 @@ vips_maplut_init( VipsMaplut *maplut )
 }
 
 /**
- * vips_maplut:
+ * vips_maplut: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @lut: look-up table
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/histogram/percent.c b/libvips/histogram/percent.c
index b952904a..7aa32c2d 100644
--- a/libvips/histogram/percent.c
+++ b/libvips/histogram/percent.c
@@ -134,10 +134,10 @@ vips_percent_init( VipsPercent *percent )
 }
 
 /**
- * vips_percent:
+ * vips_percent: (method)
  * @in: input image
  * @percent: threshold percentage
- * @threshold: output threshold value
+ * @threshold: (out): output threshold value
  * @...: %NULL-terminated list of optional named arguments
  *
  * vips_percent() returns (through the @threshold parameter) the threshold 
diff --git a/libvips/histogram/stdif.c b/libvips/histogram/stdif.c
index 92d3bdc2..f745e6a0 100644
--- a/libvips/histogram/stdif.c
+++ b/libvips/histogram/stdif.c
@@ -360,9 +360,9 @@ vips_stdif_init( VipsStdif *stdif )
 }
 
 /**
- * vips_stdif:
+ * vips_stdif: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @width: width of region
  * @height: height of region
  * @...: %NULL-terminated list of optional named arguments
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
  *
diff --git a/libvips/morphology/countlines.c b/libvips/morphology/countlines.c
index 7fbdc85b..0812dee1 100644
--- a/libvips/morphology/countlines.c
+++ b/libvips/morphology/countlines.c
@@ -157,9 +157,9 @@ vips_countlines_init( VipsCountlines *countlines )
 }
 
 /**
- * vips_countlines:
+ * vips_countlines: (method)
  * @in: input image
- * @nolines: output average number of lines
+ * @nolines: (out): output average number of lines
  * @direction: count lines horizontally or vertically
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/morphology/labelregions.c b/libvips/morphology/labelregions.c
index 880b21be..161fb754 100644
--- a/libvips/morphology/labelregions.c
+++ b/libvips/morphology/labelregions.c
@@ -142,7 +142,7 @@ vips_labelregions_init( VipsLabelregions *labelregions )
 }
 
 /**
- * vips_labelregions:
+ * vips_labelregions: (method)
  * @in: image to test
  * @mask: write labelled regions here
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/morphology/morph.c b/libvips/morphology/morph.c
index 5b38d00e..d19833a0 100644
--- a/libvips/morphology/morph.c
+++ b/libvips/morphology/morph.c
@@ -168,9 +168,9 @@ vips_morph_init( VipsMorph *morph )
 }
 
 /**
- * vips_morph:
+ * vips_morph: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @mask: morphology with this mask
  * @morph: operation to perform
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/morphology/rank.c b/libvips/morphology/rank.c
index fea8e211..d0a52851 100644
--- a/libvips/morphology/rank.c
+++ b/libvips/morphology/rank.c
@@ -447,9 +447,9 @@ vips_rank_init( VipsRank *rank )
 }
 
 /**
- * vips_rank:
+ * vips_rank: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @width: width of region
  * @height: height of region
  * @index: select pixel
@@ -491,9 +491,9 @@ vips_rank( VipsImage *in, VipsImage **out,
 }
 
 /**
- * vips_median:
+ * vips_median: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @size: size of region
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/mosaicing/global_balance.c b/libvips/mosaicing/global_balance.c
index 053330b1..4b2ba12d 100644
--- a/libvips/mosaicing/global_balance.c
+++ b/libvips/mosaicing/global_balance.c
@@ -1802,9 +1802,9 @@ vips_globalbalance_init( VipsGlobalbalance *globalbalance )
 }
 
 /**
- * vips_globalbalance:
+ * vips_globalbalance: (method)
  * @in: mosaic to rebuild
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  * 
  * Optional arguments:
diff --git a/libvips/mosaicing/im_remosaic.c b/libvips/mosaicing/im_remosaic.c
index 8d8729e0..c90db327 100644
--- a/libvips/mosaicing/im_remosaic.c
+++ b/libvips/mosaicing/im_remosaic.c
@@ -194,9 +194,9 @@ vips_remosaic_init( VipsRemosaic *remosaic )
 }
 
 /**
- * vips_remosaic:
+ * vips_remosaic: (method)
  * @in: mosaic to rebuild
- * @out: output image
+ * @out: (out): output image
  * @old_str: gamma of source images
  * @new_str: gamma of source images
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/mosaicing/match.c b/libvips/mosaicing/match.c
index 60b77594..77b142a4 100644
--- a/libvips/mosaicing/match.c
+++ b/libvips/mosaicing/match.c
@@ -315,7 +315,7 @@ vips_match_init( VipsMatch *match )
  * vips_match:
  * @ref: reference image
  * @sec: secondary image
- * @out: output image
+ * @out: (out): output image
  * @xr1: first reference tie-point
  * @yr1: first reference tie-point
  * @xs1: first secondary tie-point
diff --git a/libvips/mosaicing/merge.c b/libvips/mosaicing/merge.c
index d003deab..ad21e2e3 100644
--- a/libvips/mosaicing/merge.c
+++ b/libvips/mosaicing/merge.c
@@ -168,7 +168,7 @@ vips_merge_init( VipsMerge *merge )
  * vips_merge:
  * @ref: reference image
  * @sec: secondary image
- * @out: output image
+ * @out: (out): output image
  * @direction: horizontal or vertical merge
  * @dx: displacement of ref from sec
  * @dy: displacement of ref from sec
diff --git a/libvips/mosaicing/mosaic.c b/libvips/mosaicing/mosaic.c
index 629a1132..5ec010ef 100644
--- a/libvips/mosaicing/mosaic.c
+++ b/libvips/mosaicing/mosaic.c
@@ -314,7 +314,7 @@ vips_mosaic_init( VipsMosaic *mosaic )
  * vips_mosaic:
  * @ref: reference image
  * @sec: secondary image
- * @out: output image
+ * @out: (out): output image
  * @direction: horizontal or vertical join
  * @xref: position in reference image
  * @yref: position in reference image
diff --git a/libvips/resample/affine.c b/libvips/resample/affine.c
index 76ff1a9c..e737395c 100644
--- a/libvips/resample/affine.c
+++ b/libvips/resample/affine.c
@@ -599,9 +599,9 @@ vips_affine_init( VipsAffine *affine )
 }
 
 /**
- * vips_affine:
+ * vips_affine: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @a: transformation matrix coefficient
  * @b: transformation matrix coefficient
  * @c: transformation matrix coefficient
diff --git a/libvips/resample/interpolate.c b/libvips/resample/interpolate.c
index 66a8b24e..a002070d 100644
--- a/libvips/resample/interpolate.c
+++ b/libvips/resample/interpolate.c
@@ -617,7 +617,7 @@ vips__interpolate_init( void )
 }
 
 /**
- * vips_interpolate_new:
+ * vips_interpolate_new: (constructor)
  * @nickname: nickname for interpolator
  *
  * Look up an interpolator from a nickname and make one. You need to free the
diff --git a/libvips/resample/mapim.c b/libvips/resample/mapim.c
index d2524200..ee19c85b 100644
--- a/libvips/resample/mapim.c
+++ b/libvips/resample/mapim.c
@@ -410,9 +410,9 @@ vips_mapim_init( VipsMapim *mapim )
 }
 
 /**
- * vips_mapim:
+ * vips_mapim: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @index: index image
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -447,7 +447,7 @@ vips_mapim_init( VipsMapim *mapim )
  * Returns: 0 on success, -1 on error
  */
 int
-vips_mapim( VipsImage *in, VipsImage **out, VipsImage *index, ... ) 
+vips_mapim( VipsImage *in, VipsImage **out, VipsImage *index, ... )
 {
 	va_list ap;
 	int result;
diff --git a/libvips/resample/quadratic.c b/libvips/resample/quadratic.c
index 8db0fd6a..06363f1a 100644
--- a/libvips/resample/quadratic.c
+++ b/libvips/resample/quadratic.c
@@ -363,9 +363,9 @@ vips_quadratic_init( VipsQuadratic *quadratic )
 }
 
 /**
- * vips_quadratic:
+ * vips_quadratic: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @coeff: horizontal quadratic
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/reduce.c b/libvips/resample/reduce.c
index 6f76ade8..729a4d3a 100644
--- a/libvips/resample/reduce.c
+++ b/libvips/resample/reduce.c
@@ -183,9 +183,9 @@ vips_reduce_init( VipsReduce *reduce )
 }
 
 /**
- * vips_reduce:
+ * vips_reduce: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @hshrink: horizontal shrink
  * @vshrink: vertical shrink
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/resample/reduceh.cpp b/libvips/resample/reduceh.cpp
index 6372ce41..6922a903 100644
--- a/libvips/resample/reduceh.cpp
+++ b/libvips/resample/reduceh.cpp
@@ -610,9 +610,9 @@ vips_reduceh_init( VipsReduceh *reduceh )
 }
 
 /**
- * vips_reduceh:
+ * vips_reduceh: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @hshrink: horizontal reduce
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/reducev.cpp b/libvips/resample/reducev.cpp
index 24671621..b74a0d98 100644
--- a/libvips/resample/reducev.cpp
+++ b/libvips/resample/reducev.cpp
@@ -964,9 +964,9 @@ vips_reducev_init( VipsReducev *reducev )
 }
 
 /**
- * vips_reducev:
+ * vips_reducev: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @vshrink: horizontal reduce
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/resize.c b/libvips/resample/resize.c
index d6c6abda..1a4fafb9 100644
--- a/libvips/resample/resize.c
+++ b/libvips/resample/resize.c
@@ -352,9 +352,9 @@ vips_resize_init( VipsResize *resize )
 }
 
 /**
- * vips_resize:
+ * vips_resize: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @scale: scale factor
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/shrink.c b/libvips/resample/shrink.c
index e97fb3c1..f675ab49 100644
--- a/libvips/resample/shrink.c
+++ b/libvips/resample/shrink.c
@@ -171,9 +171,9 @@ vips_shrink_init( VipsShrink *shrink )
 }
 
 /**
- * vips_shrink:
+ * vips_shrink: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @hshrink: horizontal shrink
  * @vshrink: vertical shrink
  * @...: %NULL-terminated list of optional named arguments
diff --git a/libvips/resample/shrinkh.c b/libvips/resample/shrinkh.c
index e44f8352..97678e8f 100644
--- a/libvips/resample/shrinkh.c
+++ b/libvips/resample/shrinkh.c
@@ -342,9 +342,9 @@ vips_shrinkh_init( VipsShrinkh *shrink )
 }
 
 /**
- * vips_shrinkh:
+ * vips_shrinkh: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @hshrink: horizontal shrink
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/shrinkv.c b/libvips/resample/shrinkv.c
index bf011685..13da3218 100644
--- a/libvips/resample/shrinkv.c
+++ b/libvips/resample/shrinkv.c
@@ -470,9 +470,9 @@ vips_shrinkv_init( VipsShrinkv *shrink )
 }
 
 /**
- * vips_shrinkv:
+ * vips_shrinkv: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @vshrink: vertical shrink
  * @...: %NULL-terminated list of optional named arguments
  *
diff --git a/libvips/resample/similarity.c b/libvips/resample/similarity.c
index 89c0c6c4..35312072 100644
--- a/libvips/resample/similarity.c
+++ b/libvips/resample/similarity.c
@@ -229,9 +229,9 @@ vips_similarity_init( VipsSimilarity *similarity )
 }
 
 /**
- * vips_similarity:
+ * vips_similarity: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
diff --git a/libvips/resample/thumbnail.c b/libvips/resample/thumbnail.c
index 672c7b1a..211d09d1 100644
--- a/libvips/resample/thumbnail.c
+++ b/libvips/resample/thumbnail.c
@@ -751,7 +751,7 @@ vips_thumbnail_file_init( VipsThumbnailFile *file )
 /**
  * vips_thumbnail:
  * @filename: file to read from
- * @out: output image
+ * @out: (out): output image
  * @width: target width in pixels
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -925,9 +925,9 @@ vips_thumbnail_buffer_init( VipsThumbnailBuffer *buffer )
 
 /**
  * vips_thumbnail_buffer:
- * @buf: memory area to load
- * @len: size of memory area
- * @out: output image
+ * @buf: (array length=len) (element-type guint8): memory area to load
+ * @len: (type gsize): size of memory area
+ * @out: (out): output image
  * @width: target width in pixels
  * @...: %NULL-terminated list of optional named arguments
  *
@@ -1040,9 +1040,9 @@ vips_thumbnail_image_init( VipsThumbnailImage *image )
 }
 
 /**
- * vips_thumbnail_image:
+ * vips_thumbnail_image: (method)
  * @in: input image
- * @out: output image
+ * @out: (out): output image
  * @width: target width in pixels
  * @...: %NULL-terminated list of optional named arguments
  *