From 0d2bdac332437ca6468549c3130c8c286b82810c Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Fri, 22 Oct 2010 13:49:36 +0000
Subject: [PATCH] gtk-doc fixes

---
 ChangeLog                             |  2 +
 libvips/arithmetic/im_maxpos_vec.c    |  6 +--
 libvips/colour/colour.c               |  2 +-
 libvips/conversion/im_gbandjoin.c     | 36 +++++++++---------
 libvips/conversion/im_mask2vips.c     |  2 +-
 libvips/conversion/im_ri2c.c          |  3 +-
 libvips/conversion/im_vips2mask.c     |  8 ++--
 libvips/format/format.c               | 11 ++++++
 libvips/histograms_lut/im_histplot.c  |  2 +-
 libvips/histograms_lut/im_lhisteq.c   |  2 +-
 libvips/histograms_lut/im_stdif.c     |  2 +-
 libvips/include/vips/buf.h            |  2 +-
 libvips/include/vips/conversion.h     | 16 ++++----
 libvips/include/vips/format.h         |  2 +
 libvips/include/vips/generate.h       |  8 ++--
 libvips/include/vips/header.h         |  2 +-
 libvips/include/vips/histograms_lut.h |  6 +--
 libvips/include/vips/image.h          |  2 +-
 libvips/include/vips/mask.h           |  8 ++--
 libvips/include/vips/memory.h         |  4 +-
 libvips/include/vips/meta.h           | 27 +++++++-------
 libvips/include/vips/rect.h           |  7 +++-
 libvips/include/vips/region.h         | 30 +++++++--------
 libvips/include/vips/threadpool.h     |  2 +
 libvips/inplace/im_draw_line.c        | 24 +++++++-----
 libvips/inplace/im_draw_mask.c        | 10 ++---
 libvips/iofuncs/buf.c                 |  7 ++--
 libvips/iofuncs/check.c               |  4 +-
 libvips/iofuncs/im_generate.c         | 30 ++++++++++-----
 libvips/iofuncs/im_image.c            |  8 ++--
 libvips/iofuncs/im_open_vips.c        |  1 +
 libvips/iofuncs/meta.c                | 40 ++++++++++----------
 libvips/iofuncs/rect.c                | 10 +++++
 libvips/iofuncs/threadpool.c          |  3 +-
 libvips/mask/rw_mask.c                | 54 ++++++++++++++-------------
 35 files changed, 218 insertions(+), 165 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0620a683..dcbb3d37 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -34,6 +34,8 @@
 - im_blend() can have any format condition image and it's converted to uchar
 - security fix for vips-7.23 wrapper script (thanks Jay)
 - im_affine() has a larger safety margin
+- fix gtk-doc warnings
+- small mask load/save improvements
 
 12/5/10 started 7.22.2
 - the conditional image of ifthenelse can be any format, a (!=0) is added if
diff --git a/libvips/arithmetic/im_maxpos_vec.c b/libvips/arithmetic/im_maxpos_vec.c
index cecf9e7e..3bf63786 100644
--- a/libvips/arithmetic/im_maxpos_vec.c
+++ b/libvips/arithmetic/im_maxpos_vec.c
@@ -95,7 +95,7 @@ static int            minpos_vec_stop( void *seq, void *, void * );
  * @maxima: array to return values
  * @n: number of maxima to search for
  *
- * Find the coordinates and values of the n maxima of an image.
+ * Find the coordinates and values of the @n @maxima of an image.
  *
  * For 8 and 16-bit images, it's much faster to find the histogram and then
  * calculate a threshold from that. See im_mpercent().
@@ -157,10 +157,10 @@ int im_maxpos_vec( IMAGE *im, int *xpos, int *ypos, double *maxima, int n ){
  * @im: image to scan
  * @xpos: array to return x positions
  * @ypos: array to return y positions
- * @maxima: array to return values
+ * @minima: array to return values
  * @n: number of minima to search for
  *
- * Find the coordinates and values of the n minima of an image.
+ * Find the coordinates and values of the @n @minima of an image.
  *
  * For 8 and 16-bit images, it's much faster to find the histogram and then
  * calculate a threshold from that. See im_mpercent().
diff --git a/libvips/colour/colour.c b/libvips/colour/colour.c
index d7a73555..fcc17ae2 100644
--- a/libvips/colour/colour.c
+++ b/libvips/colour/colour.c
@@ -262,7 +262,7 @@ make_LI( void )
 
 /**
  * im_col_Lucs2L:
- * @L: L ucs
+ * @Lucs: L ucs
  *
  * Calculate L from Lucs using a table. Call im_col_make_tables_UCS() at
  * least once before using this function.
diff --git a/libvips/conversion/im_gbandjoin.c b/libvips/conversion/im_gbandjoin.c
index 6d48ef37..b9af40d8 100644
--- a/libvips/conversion/im_gbandjoin.c
+++ b/libvips/conversion/im_gbandjoin.c
@@ -66,7 +66,7 @@
 /* Struct we carry stuff around in.
  */
 typedef struct joins {
-	int nim;		/* Number of input images */
+	int n;		/* Number of input images */
 	IMAGE **in;		/* Array of input images, NULL-terminated */
 	int *is;		/* An int for SIZEOF_PEL() for each image */
 } Join;
@@ -74,31 +74,31 @@ typedef struct joins {
 /* Make a Join struct.
  */
 static Join *
-join_new( IMAGE *out, IMAGE **in, int nim )
+join_new( IMAGE *out, IMAGE **in, int n )
 {
 	Join *join;
 	int i;
 
 	if( !(join = IM_NEW( out, Join )) )
 		return( NULL );
-	join->nim = nim;
-	if( !(join->in = IM_ARRAY( out, nim + 1, IMAGE * )) || 
-		!(join->is = IM_ARRAY( out, nim, int )) ) 
+	join->n = n;
+	if( !(join->in = IM_ARRAY( out, n + 1, IMAGE * )) || 
+		!(join->is = IM_ARRAY( out, n, int )) ) 
 		return( NULL );
 
 	/* Cast inputs up to a common format.
 	 */
-	if( im_open_local_array( out, join->in, nim, "im_gbandjoin", "p" ) ||
-		im__formatalike_vec( in, join->in, nim ) )
+	if( im_open_local_array( out, join->in, n, "im_gbandjoin", "p" ) ||
+		im__formatalike_vec( in, join->in, n ) )
 		return( NULL );
 
-	for( i = 0; i < nim; i++ ) 
+	for( i = 0; i < n; i++ ) 
 		join->is[i] = IM_IMAGE_SIZEOF_PEL( join->in[i] );
 
 	/* Remember to NULL-terminate. We pass ->in[] to
 	 * im_demand_hint_array() and friends later.
 	 */
-	join->in[nim] = NULL;
+	join->in[n] = NULL;
 
 	return( join );
 }
@@ -115,7 +115,7 @@ join_bands( REGION *or, void *seq, void *a, void *b )
 
 	int x, y, z, i;
 
-	for( i = 0; i < join->nim; i++ )
+	for( i = 0; i < join->n; i++ )
 		if( im_prepare( ir[i], r ) )
 			return( -1 );
 
@@ -129,7 +129,7 @@ join_bands( REGION *or, void *seq, void *a, void *b )
 		/* Loop for each input image. Scattered write is faster than
 		 * scattered read.
 		 */
-		for( i = 0; i < join->nim; i++ ) {
+		for( i = 0; i < join->n; i++ ) {
 			int k = join->is[i];
 
 			PEL *p;
@@ -158,7 +158,7 @@ join_bands( REGION *or, void *seq, void *a, void *b )
  * im_gbandjoin:
  * @in: vector of input images
  * @out: output image
- * @nim: number of input images
+ * @n: number of input images
  *
  * Join a set of images together, bandwise. 
  * If the images
@@ -176,18 +176,18 @@ join_bands( REGION *or, void *seq, void *a, void *b )
  * Returns: 0 on success, -1 on error
  */
 int
-im_gbandjoin( IMAGE **in, IMAGE *out, int nim )
+im_gbandjoin( IMAGE **in, IMAGE *out, int n )
 {
 	int i;
 	Join *join;
 
 	/* Check it out!
 	 */
-	if( nim < 1 ) {
+	if( n < 1 ) {
 		im_error( "im_gbandjoin", "%s", _( "zero input images!" ) );
 		return( -1 );
 	}
-	else if( nim == 1 ) 
+	else if( n == 1 ) 
 		return( im_copy( in[0], out ) );
 
 	/* Check our args. 
@@ -195,7 +195,7 @@ im_gbandjoin( IMAGE **in, IMAGE *out, int nim )
 	if( im_poutcheck( out ) ||
 		im_check_coding_known( "im_gbandjoin", in[0] ) )
 		return( -1 );
-	for( i = 0; i < nim; i++ ) 
+	for( i = 0; i < n; i++ ) 
 		if( im_pincheck( in[i] ) ||
 			im_check_size_same( "im_gbandjoin", in[i], in[0] ) ||
 			im_check_coding_same( "im_gbandjoin", in[i], in[0] ) )
@@ -203,7 +203,7 @@ im_gbandjoin( IMAGE **in, IMAGE *out, int nim )
 
 	/* Build a data area.
 	 */
-	if( !(join = join_new( out, in, nim )) )
+	if( !(join = join_new( out, in, n )) )
 		return( -1 );
 
 	/* Prepare the output header.
@@ -211,7 +211,7 @@ im_gbandjoin( IMAGE **in, IMAGE *out, int nim )
 	if( im_cp_desc_array( out, join->in ) )
                 return( -1 ); 
 	out->Bands = 0;
-	for( i = 0; i < nim; i++ )
+	for( i = 0; i < n; i++ )
 		out->Bands += join->in[i]->Bands;
 	if( im_demand_hint_array( out, IM_THINSTRIP, join->in ) )
 		return( -1 );
diff --git a/libvips/conversion/im_mask2vips.c b/libvips/conversion/im_mask2vips.c
index d7067daa..31a10ecb 100644
--- a/libvips/conversion/im_mask2vips.c
+++ b/libvips/conversion/im_mask2vips.c
@@ -52,7 +52,7 @@
 /**
  * im_mask2vips:
  * @in: input mask
- * @out output image
+ * @out: output image
  *
  * Write a one-band, %IM_BANDFMT_DOUBLE image to @out based on mask @in.
  *
diff --git a/libvips/conversion/im_ri2c.c b/libvips/conversion/im_ri2c.c
index 74c39444..9d0c8c4a 100644
--- a/libvips/conversion/im_ri2c.c
+++ b/libvips/conversion/im_ri2c.c
@@ -97,7 +97,8 @@ join_buffer( PEL **p, PEL *q, int n, IMAGE *im )
  *
  * Compose two real images to make a complex image. If either @in1 or @in2 are
  * %IM_BANDFMT_DOUBLE, @out is %IM_BANDFMT_DPCOMPLEX. Otherwise @out is
- * %IM_BANDFMT_COMPLEX.
+ * %IM_BANDFMT_COMPLEX. @in1 becomes the real component fo @out and @in2 the
+ * imaginary.
  *
  * If the number of bands differs, one of the images 
  * must have one band. In this case, an n-band image is formed from the 
diff --git a/libvips/conversion/im_vips2mask.c b/libvips/conversion/im_vips2mask.c
index fadc8299..d5b75767 100644
--- a/libvips/conversion/im_vips2mask.c
+++ b/libvips/conversion/im_vips2mask.c
@@ -55,7 +55,7 @@
 /**
  * im_vips2mask:
  * @in: input image
- * @outname: name for output mask 
+ * @filename: name for output mask 
  *
  * Make a mask from an image. All images are cast to %IM_BANDFMT_DOUBLE
  * before processing. There are two cases for handling bands:
@@ -71,7 +71,7 @@
  * Returns: a #DOUBLEMASK with @outname set as the name, or NULL on error
  */
 DOUBLEMASK *
-im_vips2mask( IMAGE *in, const char *outname )
+im_vips2mask( IMAGE *in, const char *filename )
 {
 	int width, height;
 	DOUBLEMASK *out;
@@ -84,7 +84,7 @@ im_vips2mask( IMAGE *in, const char *outname )
 		if( !(t = im_open( "im_vips2mask", "p" )) )
 			return( NULL );
 		if( im_clip2fmt( in, t, IM_BANDFMT_DOUBLE ) ||
-			!(out = im_vips2mask( t, outname )) ) {
+			!(out = im_vips2mask( t, filename )) ) {
 			im_close( t );
 			return( NULL );
 		}
@@ -117,7 +117,7 @@ im_vips2mask( IMAGE *in, const char *outname )
 		return( NULL );
 	}
 
-	if( !(out = im_create_dmask( outname, width, height )) )
+	if( !(out = im_create_dmask( filename, width, height )) )
 		return( NULL );
 	if( in->Bands > 1 && in->Ysize == 1 ) {
 		double *data = (double *) in->data;
diff --git a/libvips/format/format.c b/libvips/format/format.c
index 1267dabc..8d6a5231 100644
--- a/libvips/format/format.c
+++ b/libvips/format/format.c
@@ -64,6 +64,17 @@
  * Matlab, Radiance, RAW, VIPS and one that wraps libMagick. 
  */
 
+/**
+ * VipsFormatFlags: 
+ * @VIPS_FORMAT_NONE: no flags set
+ * @VIPS_FORMAT_PARTIAL: the image may be read lazilly
+ *
+ * Some hints about the image loader.
+ *
+ * @VIPS_FORMAT_PARTIAL means that the image can be read directly from the
+ * file without needing to be unpacked to a temporary image first. 
+ */
+
 /**
  * VipsFormat:
  *
diff --git a/libvips/histograms_lut/im_histplot.c b/libvips/histograms_lut/im_histplot.c
index 07089600..34af6db5 100644
--- a/libvips/histograms_lut/im_histplot.c
+++ b/libvips/histograms_lut/im_histplot.c
@@ -310,7 +310,7 @@ plot( IMAGE *in, IMAGE *out )
  * Returns: 0 on success, -1 on error
  */
 int 
-im_histplot( IMAGE *hist, IMAGE *histplot )
+im_histplot( IMAGE *in, IMAGE *out )
 {
 	IMAGE *t1;
 
diff --git a/libvips/histograms_lut/im_lhisteq.c b/libvips/histograms_lut/im_lhisteq.c
index 29ac7230..da9e2192 100644
--- a/libvips/histograms_lut/im_lhisteq.c
+++ b/libvips/histograms_lut/im_lhisteq.c
@@ -203,7 +203,7 @@ im_lhisteq_raw( IMAGE *in, IMAGE *out, int xwin, int ywin )
  * @in: input image
  * @out: output image
  * @xwin: width of region
- * @hwin: height of region
+ * @ywin: height of region
  *
  * Performs local histogram equalisation on @in using a
  * window of size @xwin by @ywin centered on the input pixel. Works only on 
diff --git a/libvips/histograms_lut/im_stdif.c b/libvips/histograms_lut/im_stdif.c
index 19376351..f09d004b 100644
--- a/libvips/histograms_lut/im_stdif.c
+++ b/libvips/histograms_lut/im_stdif.c
@@ -245,7 +245,7 @@ im_stdif_raw( IMAGE *in, IMAGE *out,
  * @b: weight of new deviation
  * @s0:target deviation
  * @xwin: width of region
- * @hwin: height of region
+ * @ywin: height of region
  *
  * im_stdif() preforms statistical differencing according to the formula
  * given in page 45 of the book "An Introduction to Digital Image 
diff --git a/libvips/include/vips/buf.h b/libvips/include/vips/buf.h
index 45bf3360..fda8f38f 100644
--- a/libvips/include/vips/buf.h
+++ b/libvips/include/vips/buf.h
@@ -70,7 +70,7 @@ gboolean vips_buf_appendc( VipsBuf *buf, char ch );
 gboolean vips_buf_appendsc( VipsBuf *buf, gboolean quote, const char *str );
 gboolean vips_buf_appendgv( VipsBuf *buf, GValue *value );
 gboolean vips_buf_removec( VipsBuf *buf, char ch );
-gboolean vips_buf_change( VipsBuf *buf, const char *old, const char * );
+gboolean vips_buf_change( VipsBuf *buf, const char *o, const char *n );
 gboolean vips_buf_is_empty( VipsBuf *buf );
 gboolean vips_buf_is_full( VipsBuf *buf );
 const char *vips_buf_all( VipsBuf *buf );
diff --git a/libvips/include/vips/conversion.h b/libvips/include/vips/conversion.h
index 6f934667..0fbcaca1 100644
--- a/libvips/include/vips/conversion.h
+++ b/libvips/include/vips/conversion.h
@@ -37,13 +37,13 @@
 extern "C" {
 #endif /*__cplusplus*/
 
-DOUBLEMASK *im_vips2mask( IMAGE *in, const char *out );
+DOUBLEMASK *im_vips2mask( IMAGE *in, const char *filename );
 int im_mask2vips( DOUBLEMASK *in, IMAGE *out );
 
 int im_copy( IMAGE *in, IMAGE *out );
 int im_copy_set( IMAGE *in, IMAGE *out, 
 	VipsType type, float xres, float yres, int xoffset, int yoffset );
-int im_copy_set_meta( IMAGE *in, IMAGE *out, const char *field, GValue *meta );
+int im_copy_set_meta( IMAGE *in, IMAGE *out, const char *field, GValue *value );
 int im_copy_morph( IMAGE *in, IMAGE *out, 
 	int bands, VipsBandFmt bandfmt, VipsCoding coding );
 int im_copy_swap( IMAGE *in, IMAGE *out );
@@ -57,7 +57,7 @@ int im_msb_band( IMAGE *in, IMAGE *out, int band );
 
 int im_c2amph( IMAGE *in, IMAGE *out );
 int im_c2rect( IMAGE *in, IMAGE *out );
-int im_ri2c( IMAGE *real_in, IMAGE *imag_in, IMAGE *out );
+int im_ri2c( IMAGE *in1, IMAGE *in2, IMAGE *out );
 int im_c2imag( IMAGE *in, IMAGE *out );
 int im_c2real( IMAGE *in, IMAGE *out );
 int im_scaleps( IMAGE *in, IMAGE *out );
@@ -65,7 +65,7 @@ int im_scaleps( IMAGE *in, IMAGE *out );
 int im_falsecolour( IMAGE *in, IMAGE *out );
 int im_gaussnoise( IMAGE *out, int x, int y, double mean, double sigma );
 
-int im_black( IMAGE *out, int width, int height, int bands );
+int im_black( IMAGE *out, int x, int y, int bands );
 int im_text( IMAGE *out, const char *text, const char *font,
 	int width, int alignment, int dpi );
 
@@ -82,8 +82,8 @@ int im_gbandjoin( IMAGE **in, IMAGE *out, int n );
 int im_insert( IMAGE *main, IMAGE *sub, IMAGE *out, int x, int y );
 int im_insert_noexpand( IMAGE *main, IMAGE *sub, IMAGE *out, int x, int y );
 int im_insertset( IMAGE *main, IMAGE *sub, IMAGE *out, int n, int *x, int *y );
-int im_lrjoin( IMAGE *in1, IMAGE *in2, IMAGE *out );
-int im_tbjoin( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_lrjoin( IMAGE *left, IMAGE *right, IMAGE *out );
+int im_tbjoin( IMAGE *top, IMAGE *bottom, IMAGE *out );
 int im_replicate( IMAGE *in, IMAGE *out, int across, int down );
 int im_grid( IMAGE *in, IMAGE *out, int tile_height, int across, int down );
 int im_wrap( IMAGE *in, IMAGE *out, int x, int y );
@@ -94,8 +94,8 @@ int im_rot90( IMAGE *in, IMAGE *out );
 int im_rot180( IMAGE *in, IMAGE *out );
 int im_rot270( IMAGE *in, IMAGE *out );
 
-int im_subsample( IMAGE *in, IMAGE *out, int x, int y );
-int im_zoom( IMAGE *in, IMAGE *out, int x, int y );
+int im_subsample( IMAGE *in, IMAGE *out, int xshrink, int yshrink );
+int im_zoom( IMAGE *in, IMAGE *out, int xfac, int yfac );
 
 int im_system( IMAGE *im, const char *cmd, char **out );
 IMAGE *im_system_image( IMAGE *im, 
diff --git a/libvips/include/vips/format.h b/libvips/include/vips/format.h
index 40e25a70..39cc9da1 100644
--- a/libvips/include/vips/format.h
+++ b/libvips/include/vips/format.h
@@ -62,12 +62,14 @@ typedef enum {
 
 typedef struct _VipsFormat {
 	VipsObject parent_object;
+	/*< public >*/
 
 } VipsFormat;
 
 typedef struct _VipsFormatClass {
 	VipsObjectClass parent_class;
 
+	/*< public >*/
 	/* Is a file in this format.
 	 */
 	gboolean (*is_a)( const char * );
diff --git a/libvips/include/vips/generate.h b/libvips/include/vips/generate.h
index 85ded08e..0077b5ea 100644
--- a/libvips/include/vips/generate.h
+++ b/libvips/include/vips/generate.h
@@ -45,10 +45,10 @@ typedef void *(*im_start_fn)( IMAGE *out, void *a, void *b );
 typedef int (*im_generate_fn)( REGION *out, void *seq, void *a, void *b );
 typedef int (*im_stop_fn)( void *seq, void *a, void *b );
 
-void *im_start_one( IMAGE *out, void *in, void *dummy );
-int im_stop_one( void *seq, void *dummy1, void *dummy2 );
-void *im_start_many( IMAGE *out, void *in, void *dummy );
-int im_stop_many( void *seq, void *dummy1, void *dummy2 );
+void *im_start_one( IMAGE *out, void *a, void *b );
+int im_stop_one( void *seq, void *a, void *b );
+void *im_start_many( IMAGE *out, void *a, void *b );
+int im_stop_many( void *seq, void *a, void *b );
 IMAGE **im_allocate_input_array( IMAGE *out, ... )
 	__attribute__((sentinel));
 
diff --git a/libvips/include/vips/header.h b/libvips/include/vips/header.h
index 67287c24..52629104 100644
--- a/libvips/include/vips/header.h
+++ b/libvips/include/vips/header.h
@@ -47,7 +47,7 @@ int im_header_get( IMAGE *im, const char *field, GValue *value_copy );
 typedef void *(*im_header_map_fn)( IMAGE *, const char *, GValue *, void * );
 void *im_header_map( IMAGE *im, im_header_map_fn fn, void *a );
 
-int im_histlin( IMAGE *image, const char *fmt, ... )
+int im_histlin( IMAGE *im, const char *fmt, ... )
 	__attribute__((format(printf, 2, 3)));
 int im_updatehist( IMAGE *out, const char *name, int argc, char *argv[] );
 const char *im_history_get( IMAGE *im );
diff --git a/libvips/include/vips/histograms_lut.h b/libvips/include/vips/histograms_lut.h
index 8577747c..da47d017 100644
--- a/libvips/include/vips/histograms_lut.h
+++ b/libvips/include/vips/histograms_lut.h
@@ -50,9 +50,9 @@ int im_project( IMAGE *in, IMAGE *hout, IMAGE *vout );
 int im_histnorm( IMAGE *in, IMAGE *out );
 int im_histcum( IMAGE *in, IMAGE *out );
 int im_histeq( IMAGE *in, IMAGE *out );
-int im_histspec( IMAGE *hin, IMAGE *href, IMAGE *lut );
+int im_histspec( IMAGE *in, IMAGE *ref, IMAGE *out );
 int im_ismonotonic( IMAGE *lut, int *out );
-int im_histplot( IMAGE *hist, IMAGE *histplot );
+int im_histplot( IMAGE *in, IMAGE *out );
 
 int im_maplut( IMAGE *in, IMAGE *out, IMAGE *lut );
 
@@ -74,7 +74,7 @@ int im_tone_build_range( IMAGE *out,
 int im_tone_build( IMAGE *out,
 	double Lb, double Lw, double Ps, double Pm, double Ph,
 	double S, double M, double H );
-int im_tone_analyse( IMAGE *in, IMAGE *lut,
+int im_tone_analyse( IMAGE *in, IMAGE *out,
 	double Ps, double Pm, double Ph, double S, double M, double H );
 int im_tone_map( IMAGE *in, IMAGE *out, IMAGE *lut );
 
diff --git a/libvips/include/vips/image.h b/libvips/include/vips/image.h
index 0316ed55..574de6f8 100644
--- a/libvips/include/vips/image.h
+++ b/libvips/include/vips/image.h
@@ -334,7 +334,7 @@ int im_cp_desc_array( VipsImage *out, VipsImage *in[] );
 VipsImage *im_binfile( const char *name, 
 	int xsize, int ysize, int bands, int offset );
 VipsImage *im_image( void *buffer, 
-	int width, int height, int bands, VipsBandFmt bandfmt );
+	int xsize, int ysize, int bands, VipsBandFmt bandfmt );
 
 #ifdef __cplusplus
 }
diff --git a/libvips/include/vips/mask.h b/libvips/include/vips/mask.h
index fa9e3761..abf33588 100644
--- a/libvips/include/vips/mask.h
+++ b/libvips/include/vips/mask.h
@@ -55,10 +55,10 @@ typedef struct im__DOUBLEMASK {
 	char *filename;
 } DOUBLEMASK;
 
-INTMASK *im_create_imask( const char *filename, int width, int height );
-INTMASK *im_create_imaskv( const char *filename, int width, int height, ... );
-DOUBLEMASK *im_create_dmask( const char *filename, int width, int height );
-DOUBLEMASK *im_create_dmaskv( const char *filename, int width, int height, ... );
+INTMASK *im_create_imask( const char *filename, int xsize, int ysize );
+INTMASK *im_create_imaskv( const char *filename, int xsize, int ysize, ... );
+DOUBLEMASK *im_create_dmask( const char *filename, int xsize, int ysize );
+DOUBLEMASK *im_create_dmaskv( const char *filename, int xsize, int ysize, ... );
 
 INTMASK *im_read_imask( const char *filename );
 DOUBLEMASK *im_read_dmask( const char *filename );
diff --git a/libvips/include/vips/memory.h b/libvips/include/vips/memory.h
index 5d39e779..7ea6c44d 100644
--- a/libvips/include/vips/memory.h
+++ b/libvips/include/vips/memory.h
@@ -39,8 +39,8 @@ extern "C" {
 #define IM_NEW( IM, T ) ((T *) im_malloc( (IM), sizeof( T )))
 #define IM_ARRAY( IM, N, T ) ((T *) im_malloc( (IM), (N) * sizeof( T )))
 
-void *im_malloc( VipsImage *im, size_t sz );
-int im_free( void * );
+void *im_malloc( VipsImage *im, size_t size );
+int im_free( void *s );
 
 #ifdef __cplusplus
 }
diff --git a/libvips/include/vips/meta.h b/libvips/include/vips/meta.h
index 74cce5dc..e94492e9 100644
--- a/libvips/include/vips/meta.h
+++ b/libvips/include/vips/meta.h
@@ -102,27 +102,28 @@ size_t im_ref_string_get_length( const GValue *value );
  */
 #define IM_TYPE_BLOB (im_blob_get_type())
 GType im_blob_get_type( void );
-void *im_blob_get( const GValue *value, size_t *data_length );
+void *im_blob_get( const GValue *value, size_t *length );
 int im_blob_set( GValue *value, im_callback_fn free_fn, 
 	void *data, size_t length ); 
 
-int im_meta_set( IMAGE *, const char *field, GValue * );
+int im_meta_set( IMAGE *im, const char *field, GValue *value );
 gboolean im_meta_remove( IMAGE *im, const char *field );
-int im_meta_get( IMAGE *, const char *field, GValue * );
+int im_meta_get( IMAGE *im, const char *field, GValue *value_copy );
 GType im_meta_get_typeof( IMAGE *im, const char *field );
 
-int im_meta_set_int( IMAGE *, const char *field, int i );
-int im_meta_get_int( IMAGE *, const char *field, int *i );
-int im_meta_set_double( IMAGE *, const char *field, double d );
-int im_meta_get_double( IMAGE *, const char *field, double *d );
-int im_meta_set_area( IMAGE *, const char *field, im_callback_fn, void * );
-int im_meta_get_area( IMAGE *, const char *field, void **data );
-int im_meta_set_string( IMAGE *, const char *field, const char *str );
-int im_meta_get_string( IMAGE *, const char *field, char **str );
+int im_meta_set_int( IMAGE *im, const char *field, int i );
+int im_meta_get_int( IMAGE *im, const char *field, int *i );
+int im_meta_set_double( IMAGE *im, const char *field, double d );
+int im_meta_get_double( IMAGE *im, const char *field, double *d );
+int im_meta_set_area( IMAGE *im, 
+	const char *field, im_callback_fn free_fn, void *data );
+int im_meta_get_area( IMAGE *im, const char *field, void **data );
+int im_meta_set_string( IMAGE *im, const char *field, const char *str );
+int im_meta_get_string( IMAGE *im, const char *field, char **str );
 int im_meta_set_blob( IMAGE *im, const char *field, 
-	im_callback_fn free_fn, void *blob, size_t blob_length );
+	im_callback_fn free_fn, void *data, size_t length );
 int im_meta_get_blob( IMAGE *im, const char *field, 
-	void **blob, size_t *blob_length );
+	void **data, size_t *length );
 
 #ifdef __cplusplus
 }
diff --git a/libvips/include/vips/rect.h b/libvips/include/vips/rect.h
index 7ea5e48a..940f0146 100644
--- a/libvips/include/vips/rect.h
+++ b/libvips/include/vips/rect.h
@@ -36,8 +36,11 @@ extern "C" {
 
 /* A rectangle.
  */
-typedef struct im_rect_struct {
-	int left, top, width, height;
+typedef struct _Rect {
+	int left;
+	int top;
+	int width;
+	int height;
 } Rect;
 
 #define IM_RECT_RIGHT(R) ((R)->left + (R)->width)
diff --git a/libvips/include/vips/region.h b/libvips/include/vips/region.h
index fc0a8c12..47efc58c 100644
--- a/libvips/include/vips/region.h
+++ b/libvips/include/vips/region.h
@@ -77,9 +77,9 @@ void im_region_free( REGION *reg );
 
 int im_region_buffer( REGION *reg, Rect *r );
 int im_region_image( REGION *reg, Rect *r );
-int im_region_region( REGION *reg, REGION *to, Rect *r, int x, int y );
+int im_region_region( REGION *reg, REGION *dest, Rect *r, int x, int y );
 int im_region_equalsregion( REGION *reg1, REGION *reg2 );
-int im_region_position( REGION *reg1, int x, int y );
+int im_region_position( REGION *reg, int x, int y );
 
 void im_region_paint( REGION *reg, Rect *r, int value );
 void im_region_black( REGION *reg );
@@ -101,10 +101,10 @@ void im_region_copy( REGION *reg, REGION *dest, Rect *r, int x, int y );
 /* If DEBUG is defined, add bounds checking.
  */
 #ifdef DEBUG
-#define IM_REGION_ADDR(B,X,Y) \
-	( (im_rect_includespoint( &(B)->valid, (X), (Y) ))? \
-	  ((B)->data + ((Y) - (B)->valid.top) * IM_REGION_LSKIP(B) + \
-	  ((X) - (B)->valid.left) * IM_IMAGE_SIZEOF_PEL((B)->im)): \
+#define IM_REGION_ADDR(R,X,Y) \
+	( (im_rect_includespoint( &(R)->valid, (X), (Y) ))? \
+	  ((R)->data + ((Y) - (R)->valid.top) * IM_REGION_LSKIP(R) + \
+	  ((X) - (R)->valid.left) * IM_IMAGE_SIZEOF_PEL((R)->im)): \
 	  (fprintf( stderr, \
 		"IM_REGION_ADDR: point out of bounds, " \
 		"file \"%s\", line %d\n" \
@@ -113,19 +113,19 @@ void im_region_copy( REGION *reg, REGION *dest, Rect *r, int x, int y );
 		"width=%d, height=%d)\n", \
 		__FILE__, __LINE__, \
 		(X), (Y), \
-		(B)->valid.left, \
-		(B)->valid.top, \
-		(B)->valid.width, \
-		(B)->valid.height ), abort(), (char *) NULL) \
+		(R)->valid.left, \
+		(R)->valid.top, \
+		(R)->valid.width, \
+		(R)->valid.height ), abort(), (char *) NULL) \
 	)
 #else /*DEBUG*/
-#define IM_REGION_ADDR(B,X,Y) \
-	((B)->data + \
-	((Y)-(B)->valid.top) * IM_REGION_LSKIP(B) + \
-	((X)-(B)->valid.left) * IM_IMAGE_SIZEOF_PEL((B)->im))
+#define IM_REGION_ADDR(R,X,Y) \
+	((R)->data + \
+	((Y)-(R)->valid.top) * IM_REGION_LSKIP(R) + \
+	((X)-(R)->valid.left) * IM_IMAGE_SIZEOF_PEL((R)->im))
 #endif /*DEBUG*/
 
-#define IM_REGION_ADDR_TOPLEFT(B)   ( (B)->data )
+#define IM_REGION_ADDR_TOPLEFT(R)   ( (R)->data )
 
 #ifdef __cplusplus
 }
diff --git a/libvips/include/vips/threadpool.h b/libvips/include/vips/threadpool.h
index 8cdcd170..6d1c044f 100644
--- a/libvips/include/vips/threadpool.h
+++ b/libvips/include/vips/threadpool.h
@@ -64,6 +64,7 @@ extern "C" {
 typedef struct _VipsThreadState {
 	VipsObject parent_object;
 
+	/*< public >*/
 	/* Image we run on.
 	 */
 	VipsImage *im;
@@ -86,6 +87,7 @@ typedef struct _VipsThreadState {
 
 typedef struct _VipsThreadStateClass {
 	VipsObjectClass parent_class;
+	/*< public >*/
 
 } VipsThreadStateClass;
 
diff --git a/libvips/inplace/im_draw_line.c b/libvips/inplace/im_draw_line.c
index 1b2376f5..9ee5548b 100644
--- a/libvips/inplace/im_draw_line.c
+++ b/libvips/inplace/im_draw_line.c
@@ -269,13 +269,19 @@ line_draw( Line *line )
 
 /**
  * VipsPlotFn:
+ * @image: image to draw on
+ * @x: position to draw at
+ * @y: position to draw at
+ * @a: user data
+ * @b: user data
+ * @c: user data
  *
  * A plot function, as used by im_draw_line_user() to draw on an image. 
  */
 
 /**
  * im_draw_line_user:
- * @im: image to draw on
+ * @image: image to draw on
  * @x1: start point
  * @y1: start point
  * @x2: end point
@@ -294,14 +300,14 @@ line_draw( Line *line )
  * Returns: 0 on success, or -1 on error.
  */
 int 
-im_draw_line_user( VipsImage *im, 
+im_draw_line_user( VipsImage *image, 
 	int x1, int y1, int x2, int y2, 
 	VipsPlotFn plot, void *a, void *b, void *c )
 {
 	Line *line;
 
-	if( im_check_coding_known( "im_draw_line_user", im ) ||
-		!(line = line_new( im, x1, y1, x2, y2, NULL )) )
+	if( im_check_coding_known( "im_draw_line_user", image ) ||
+		!(line = line_new( image, x1, y1, x2, y2, NULL )) )
 		return( -1 );
 
 	line->plot = plot;
@@ -334,7 +340,7 @@ line_plot_point( VipsImage *im, int x, int y,
 
 /**
  * im_draw_line:
- * @im: image to draw on
+ * @image: image to draw on
  * @x1: start point
  * @y1: start point
  * @x2: end point
@@ -345,19 +351,19 @@ line_plot_point( VipsImage *im, int x, int y,
  *
  * @ink is an array of bytes 
  * containing a valid pixel for the image's format.
- * It must have at least IM_IMAGE_SIZEOF_PEL( @im ) bytes.
+ * It must have at least IM_IMAGE_SIZEOF_PEL( @image ) bytes.
  *
  * See also: im_draw_circle().
  *
  * Returns: 0 on success, or -1 on error.
  */
 int 
-im_draw_line( VipsImage *im, int x1, int y1, int x2, int y2, PEL *ink )
+im_draw_line( VipsImage *image, int x1, int y1, int x2, int y2, PEL *ink )
 {
 	Line *line;
 
-	if( im_check_coding_known( "im_draw_line", im ) ||
-		!(line = line_new( im, x1, y1, x2, y2, ink )) ) 
+	if( im_check_coding_known( "im_draw_line", image ) ||
+		!(line = line_new( image, x1, y1, x2, y2, ink )) ) 
 		return( -1 );
 
 	line->plot = line_plot_point;
diff --git a/libvips/inplace/im_draw_mask.c b/libvips/inplace/im_draw_mask.c
index 6bc0440d..7d5f784d 100644
--- a/libvips/inplace/im_draw_mask.c
+++ b/libvips/inplace/im_draw_mask.c
@@ -266,7 +266,7 @@ mask_draw( Mask *mask )
 
 /**
  * im_draw_mask:
- * @im: image to draw on
+ * @image: image to draw on
  * @x: draw mask here
  * @y: draw mask here
  * @ink: value to draw
@@ -278,18 +278,18 @@ mask_draw( Mask *mask )
  *
  * @ink is an array of bytes 
  * containing a valid pixel for the image's format.
- * It must have at least IM_IMAGE_SIZEOF_PEL( @im ) bytes.
+ * It must have at least IM_IMAGE_SIZEOF_PEL( @image ) bytes.
  *
  * See also: im_draw_circle(), im_text(), im_draw_line_user().
  *
  * Returns: 0 on success, or -1 on error.
  */
 int
-im_draw_mask( VipsImage *im, VipsImage *mask_im, int x, int y, PEL *ink )
+im_draw_mask( VipsImage *image, VipsImage *mask_im, int x, int y, PEL *ink )
 {
 	Mask *mask;
 
-	if( !(mask = mask_new( im, x, y, ink, mask_im )) )
+	if( !(mask = mask_new( image, x, y, ink, mask_im )) )
 		return( -1 );
 
 	/* Any points to plot?
@@ -301,7 +301,7 @@ im_draw_mask( VipsImage *im, VipsImage *mask_im, int x, int y, PEL *ink )
 
 	/* Loop through image plotting where required.
 	 */
-	switch( im->Coding ) {
+	switch( image->Coding ) {
 	case IM_CODING_LABQ:
 		if( mask_draw_labq( mask ) ) {
 			mask_free( mask );
diff --git a/libvips/iofuncs/buf.c b/libvips/iofuncs/buf.c
index b8a899d4..f283587b 100644
--- a/libvips/iofuncs/buf.c
+++ b/libvips/iofuncs/buf.c
@@ -84,7 +84,6 @@
 /** 
  * VIPS_BUF_STATIC:
  * @TEXT: the storage area to use
- * @MAX: the size of the storage area
  *
  * Initialize a heap buffer. For example:
  *
@@ -340,10 +339,10 @@ vips_buf_appendc( VipsBuf *buf, char ch )
 /**
  * vips_buf_change:
  * @buf: the buffer
- * @old: the string to search for
- * @new: the string to substitute
+ * @o: the string to search for
+ * @n: the string to substitute
  *
- * Swap the rightmost occurence of @old for @new.
+ * Swap the rightmost occurence of @o for @n.
  * 
  * Returns: %FALSE on overflow, %TRUE otherwise.
  */
diff --git a/libvips/iofuncs/check.c b/libvips/iofuncs/check.c
index f85e6a3d..b3f36468 100644
--- a/libvips/iofuncs/check.c
+++ b/libvips/iofuncs/check.c
@@ -774,7 +774,7 @@ im_check_bands_1orn( const char *domain, IMAGE *im1, IMAGE *im2 )
 /**
  * im_check_bands_1orn_unary:
  * @domain: the originating domain for the error message
- * @im1: image to check
+ * @im: image to check
  * @n: number of bands, or 1
  *
  * Check that an image has 1 or @n bands. Handy for unary operations, cf.
@@ -1361,7 +1361,7 @@ vips_bandfmt_isfloat( VipsBandFmt fmt )
 
 /**
  * vips_bandfmt_iscomplex:
- * @im: image to test
+ * @fmt: format to test
  *
  * Return %TRUE if @fmt is one of the complex types.
  */
diff --git a/libvips/iofuncs/im_generate.c b/libvips/iofuncs/im_generate.c
index 0d2d034f..8ac8c485 100644
--- a/libvips/iofuncs/im_generate.c
+++ b/libvips/iofuncs/im_generate.c
@@ -118,28 +118,34 @@
 
 /**
  * im_start_one:
+ * @out: image to generate
+ * @a: user data
+ * @b: user data
  *
  * Start function for one image in. Input image is first user data.
  *
  * See also: im_generate().
  */
 void *
-im_start_one( IMAGE *out, void *client, void *dummy )
+im_start_one( IMAGE *out, void *a, void *b )
 {
-	IMAGE *in = (IMAGE *) client;
+	IMAGE *in = (IMAGE *) a;
 
 	return( im_region_create( in ) );
 }
 
 /**
  * im_stop_one:
+ * @seq: sequence value
+ * @a: user data
+ * @b: user data
  *
- * Stop function for one image in. Input image is first user data.
+ * Stop function for one image in. Input image is @a.
  *
  * See also: im_generate().
  */
 int
-im_stop_one( void *seq, void *dummy1, void *dummy2 )
+im_stop_one( void *seq, void *a, void *b )
 {
 	REGION *reg = (REGION *) seq;
 
@@ -150,14 +156,17 @@ im_stop_one( void *seq, void *dummy1, void *dummy2 )
 
 /**
  * im_stop_many:
+ * @seq: sequence value
+ * @a: user data
+ * @b: user data
  *
- * Stop function for many images in. First client is a pointer to 
+ * Stop function for many images in. First user data is a pointer to 
  * a %NULL-terminated array of input images.
  *
  * See also: im_generate().
  */
 int
-im_stop_many( void *seq, void *dummy1, void *dummy2 )
+im_stop_many( void *seq, void *a, void *b )
 {
 	REGION **ar = (REGION **) seq;
 
@@ -174,16 +183,19 @@ im_stop_many( void *seq, void *dummy1, void *dummy2 )
 
 /**
  * im_start_many:
+ * @out: image to generate
+ * @a: user data
+ * @b: user data
  *
- * Start function for many images in. First client is a pointer to 
+ * Start function for many images in. @a is a pointer to 
  * a %NULL-terminated array of input images.
  *
  * See also: im_generate(), im_allocate_input_array()
  */
 void *
-im_start_many( IMAGE *out, void *client, void *dummy )
+im_start_many( IMAGE *out, void *a, void *b )
 {
-	IMAGE **in = (IMAGE **) client;
+	IMAGE **in = (IMAGE **) a;
 
 	int i, n;
 	REGION **ar;
diff --git a/libvips/iofuncs/im_image.c b/libvips/iofuncs/im_image.c
index a2d83953..4d888a66 100644
--- a/libvips/iofuncs/im_image.c
+++ b/libvips/iofuncs/im_image.c
@@ -64,11 +64,11 @@
  * Returns: the new #IMAGE, or %NULL on error.
  */
 IMAGE *
-im_image( void *buffer, int width, int height, int bands, VipsBandFmt bandfmt )
+im_image( void *buffer, int xsize, int ysize, int bands, VipsBandFmt bandfmt )
 {
 	IMAGE *im;
 
-	if( width <= 0 || height <= 0 || bands <= 0 || 
+	if( xsize <= 0 || ysize <= 0 || bands <= 0 || 
 		bandfmt < 0 || bandfmt > IM_BANDFMT_DPCOMPLEX ) {
 		im_error( "im_image", "%s", _( "bad parameters" ) );
 		return( NULL );
@@ -81,8 +81,8 @@ im_image( void *buffer, int width, int height, int bands, VipsBandFmt bandfmt )
 
 	/* Set header fields.
 	 */
-	im->Xsize = width;
-	im->Ysize = height;
+	im->Xsize = xsize;
+	im->Ysize = ysize;
 	im->Bands = bands;
 	im->BandFmt = bandfmt;
 	im->Bbits = im_bits_of_fmt( bandfmt );
diff --git a/libvips/iofuncs/im_open_vips.c b/libvips/iofuncs/im_open_vips.c
index badf1f9a..e5aba684 100644
--- a/libvips/iofuncs/im_open_vips.c
+++ b/libvips/iofuncs/im_open_vips.c
@@ -170,6 +170,7 @@
 
 /**
  * VipsBandFmt: 
+ * @IM_BANDFMT_NOTSET: invalid setting
  * @IM_BANDFMT_UCHAR: unsigned char format
  * @IM_BANDFMT_CHAR: char format
  * @IM_BANDFMT_USHORT: unsigned short format
diff --git a/libvips/iofuncs/meta.c b/libvips/iofuncs/meta.c
index 421315d8..1d504df1 100644
--- a/libvips/iofuncs/meta.c
+++ b/libvips/iofuncs/meta.c
@@ -1088,17 +1088,17 @@ im_meta_get_string( IMAGE *im, const char *field, char **str )
 /** 
  * im_blob_get:
  * @value: GValue to get from
- * @blob_length: return the blob length here, optionally
+ * @length: return the blob length here, optionally
  *
  * Get the address of the blob (binary large object) being held in @value and
- * optionally return its length in @blob_length.
+ * optionally return its length in @length.
  *
- * See also: im_blob_set()
+ * See also: im_blob_set().
  *
  * Returns: The blob address.
  */
 void *
-im_blob_get( const GValue *value, size_t *blob_length )
+im_blob_get( const GValue *value, size_t *length )
 {
 	Area *area;
 
@@ -1107,8 +1107,8 @@ im_blob_get( const GValue *value, size_t *blob_length )
 	 */
 
 	area = g_value_get_boxed( value );
-	if( blob_length )
-		*blob_length = area->length;
+	if( length )
+		*length = area->length;
 
 	return( area->data );
 }
@@ -1181,8 +1181,8 @@ im_blob_get_type( void )
  * im_blob_set:
  * @value: GValue to set
  * @free_fn: free function for @data
- * @blob: pointer to area of memory
- * @blob_length: length of memory area
+ * @data: pointer to area of memory
+ * @length: length of memory area
  *
  * Sets @value to hold a pointer to @blob. When @value is freed, @blob will be
  * freed with @free_fn. @value also holds a note of the length of the memory
@@ -1198,13 +1198,13 @@ im_blob_get_type( void )
  */
 int
 im_blob_set( GValue *value, 
-	im_callback_fn free_fn, void *blob, size_t blob_length ) 
+	im_callback_fn free_fn, void *data, size_t length ) 
 {
 	Area *area;
 
 	g_assert( G_VALUE_TYPE( value ) == IM_TYPE_BLOB );
 
-	if( !(area = area_new_blob( free_fn, blob, blob_length )) )
+	if( !(area = area_new_blob( free_fn, blob, length )) )
 		return( -1 );
 
 	g_value_set_boxed( value, area );
@@ -1218,8 +1218,8 @@ im_blob_set( GValue *value,
  * @im: image to attach the metadata to
  * @field: metadata name
  * @free_fn: free function for @data
- * @blob: pointer to area of memory
- * @blob_length: length of memory area
+ * @data: pointer to area of memory
+ * @length: length of memory area
  *
  * Attaches @blob as a metadata item on @im under the name @field. A convenience
  * function over im_meta_set() using an im_blob.
@@ -1230,12 +1230,12 @@ im_blob_set( GValue *value,
  */
 int
 im_meta_set_blob( IMAGE *im, const char *field, 
-	im_callback_fn free_fn, void *blob, size_t blob_length )
+	im_callback_fn free_fn, void *data, size_t length )
 {
 	GValue value = { 0 };
 
 	g_value_init( &value, IM_TYPE_BLOB );
-	im_blob_set( &value, free_fn, blob, blob_length );
+	im_blob_set( &value, free_fn, blob, length );
 
 	return( meta_set_value( im, field, &value ) );
 }
@@ -1244,28 +1244,28 @@ im_meta_set_blob( IMAGE *im, const char *field,
  * im_meta_get_blob:
  * @im: image to get the metadata from
  * @field: metadata name
- * @blob: pointer to area of memory
- * @blob_length: return the blob length here, optionally
+ * @data: pointer to area of memory
+ * @length: return the blob length here, optionally
  *
  * Gets @blob from @im under the name @field, optionally return its length in
- * @blob_length. A convenience
+ * @length. A convenience
  * function over im_meta_get(). Use im_meta_get_typeof() to test for the 
  * existance
  * of a piece of metadata.
  *
- * See also: im_meta_get(), im_meta_get_typeof(), im_blob_get(), im_blob
+ * See also: im_meta_get(), im_meta_get_typeof(), im_blob_get(), 
  *
  * Returns: 0 on success, -1 otherwise.
  */
 int
 im_meta_get_blob( IMAGE *im, const char *field, 
-	void **blob, size_t *blob_length )
+	void **data, size_t *length )
 {
 	GValue value_copy = { 0 };
 
 	if( meta_get_value( im, field, IM_TYPE_BLOB, &value_copy ) )
 		return( -1 );
-	*blob = im_blob_get( &value_copy, blob_length );
+	*blob = im_blob_get( &value_copy, length );
 	g_value_unset( &value_copy );
 
 	return( 0 );
diff --git a/libvips/iofuncs/rect.c b/libvips/iofuncs/rect.c
index 7eb59222..836fc48a 100644
--- a/libvips/iofuncs/rect.c
+++ b/libvips/iofuncs/rect.c
@@ -43,6 +43,16 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * Rect:
+ * @left: left edge of rectangle
+ * @top: top edge of rectangle
+ * @width: width of rectangle
+ * @height: height of rectangle
+ *
+ * A #Rect is a rectangular area of pixels. 
+ */
+
 /* Move the margins of a rect. +1 means out one pixel.
  */
 void
diff --git a/libvips/iofuncs/threadpool.c b/libvips/iofuncs/threadpool.c
index a627c9cc..e247e83f 100644
--- a/libvips/iofuncs/threadpool.c
+++ b/libvips/iofuncs/threadpool.c
@@ -229,7 +229,8 @@ im_concurrency_get( void )
 }
 
 /**
- * _VipsThreadState:
+ * VipsThreadState:
+ * @im: the #VipsImage being operated upon
  * @reg: a #REGION
  * @pos: a #Rect
  * @x: an int
diff --git a/libvips/mask/rw_mask.c b/libvips/mask/rw_mask.c
index 496763ef..9b386e69 100644
--- a/libvips/mask/rw_mask.c
+++ b/libvips/mask/rw_mask.c
@@ -209,8 +209,8 @@ im_free_dmask( DOUBLEMASK *m )
 /**
  * im_create_imask:
  * @filename: set mask filename to this
- * @xs: mask width
- * @ys: mask height
+ * @xsize: mask width
+ * @ysize: mask height
  *
  * Create an empty imask. You need to loop over @coeff to set the values. 
  *
@@ -219,14 +219,14 @@ im_free_dmask( DOUBLEMASK *m )
  * Returns: The newly-allocated mask.
  */
 INTMASK *
-im_create_imask( const char *filename, int xs, int ys )
+im_create_imask( const char *filename, int xsize, int ysize )
 {	
 	INTMASK *m;
-	int size = xs * ys;
+	int size = xsize * ysize;
 
 	/* Check args.
 	 */
-	if( xs <= 0 || ys <= 0 || filename == NULL ) { 
+	if( xsize <= 0 || ysize <= 0 || filename == NULL ) { 
 		im_error( "im_create_imask", "%s", _( "bad arguments" ) ); 
 		return( NULL );
 	}
@@ -251,7 +251,8 @@ im_create_imask( const char *filename, int xs, int ys )
 		im_free_imask( m );
 		return( NULL );
 	}
-	m->xsize = xs; m->ysize = ys;
+	m->xsize = xsize; 
+	m->ysize = ysize;
 
 	return( m );
 }
@@ -259,8 +260,8 @@ im_create_imask( const char *filename, int xs, int ys )
 /**
  * im_create_imaskv:
  * @filename: set mask filename to this
- * @xs: mask width
- * @ys: mask height
+ * @xsize: mask width
+ * @ysize: mask height
  * @Varargs: values to set for the mask
  *
  * Create an imask and initialise it from the funtion parameter list.
@@ -270,18 +271,18 @@ im_create_imask( const char *filename, int xs, int ys )
  * Returns: The newly-allocated mask.
  */
 INTMASK *
-im_create_imaskv( const char *filename, int xs, int ys, ... )
+im_create_imaskv( const char *filename, int xsize, int ysize, ... )
 {
 	va_list ap;
 
 	INTMASK *m;
 	int i;
 
-	if( !(m = im_create_imask( filename, xs, ys )) )
+	if( !(m = im_create_imask( filename, xsize, ysize )) )
 		return( NULL );
 
-	va_start( ap, ys );
-	for( i = 0; i < xs * ys; i++ )
+	va_start( ap, ysize );
+	for( i = 0; i < xsize * ysize; i++ )
 		m->coeff[i] = va_arg( ap, int );
 	va_end( ap );
 
@@ -291,24 +292,24 @@ im_create_imaskv( const char *filename, int xs, int ys, ... )
 /**
  * im_create_dmask:
  * @filename: set mask filename to this
- * @xs: mask width
- * @ys: mask height
+ * @xsize: mask width
+ * @ysize: mask height
  *
  * Create an empty dmask. You need to loop over @coeff to set the values. 
  *
- * See also: im_create_dmaskv().
+ * See also: im_create_dmaskv(), im_vips2mask().
  *
  * Returns: The newly-allocated mask.
  */
 DOUBLEMASK *
-im_create_dmask( const char *filename, int xs, int ys )
+im_create_dmask( const char *filename, int xsize, int ysize )
 {	
 	DOUBLEMASK *m;
-	int size = xs * ys;
+	int size = xsize * ysize;
 
 	/* Check args.
 	 */
-	if( xs <= 0 || ys <= 0 || filename == NULL ) { 
+	if( xsize <= 0 || ysize <= 0 || filename == NULL ) { 
 		im_error( "im_create_dmask", "%s", _( "bad arguments" ) ); 
 		return( NULL );
 	}
@@ -333,7 +334,8 @@ im_create_dmask( const char *filename, int xs, int ys )
 		im_free_dmask( m );
 		return( NULL );
 	}
-	m->xsize = xs; m->ysize = ys;
+	m->xsize = xsize; 
+	m->ysize = ysize;
 
 	return( m );
 }
@@ -341,8 +343,8 @@ im_create_dmask( const char *filename, int xs, int ys )
 /**
  * im_create_dmaskv:
  * @filename: set mask filename to this
- * @xs: mask width
- * @ys: mask height
+ * @xsize: mask width
+ * @ysize: mask height
  * @Varargs: values to set for the mask
  *
  * Create a dmask and initialise it from the funtion parameter list.
@@ -352,18 +354,18 @@ im_create_dmask( const char *filename, int xs, int ys )
  * Returns: The newly-allocated mask.
  */
 DOUBLEMASK *
-im_create_dmaskv( const char *filename, int xs, int ys, ... )
+im_create_dmaskv( const char *filename, int xsize, int ysize, ... )
 {	
 	va_list ap;
 
 	DOUBLEMASK *m;
 	int i;
 
-	if( !(m = im_create_dmask( filename, xs, ys )) )
+	if( !(m = im_create_dmask( filename, xsize, ysize )) )
 		return( NULL );
 
-	va_start( ap, ys );
-	for( i = 0; i < xs * ys; i++ )
+	va_start( ap, ysize );
+	for( i = 0; i < xsize * ysize; i++ )
 		m->coeff[i] = va_arg( ap, double );
 	va_end( ap );
 
@@ -633,7 +635,7 @@ im_scale_dmask( DOUBLEMASK *m, const char *filename )
 
 /**
  * im_norm_dmask:
- * @m: mask to scale
+ * @mask: mask to scale
  *
  * Normalise the dmask. Apply the scale and offset to each element and return
  * a mask with scale 1, offset zero.