more pyvips8 docs

and cleanups of various small doc markup errors

TODO

@@ -1,16 +1,26 @@
 - try:
 
-	$ vipsthumbnail 360mp.png --vips-leak --vips-concurrency=1
+	$ vipsthumbnail 360mp.png --vips-leak --vips-concurrency=1 --vips-progress
-	--vips-progress
-
 
   works in tiles ... should it be strips?
 
   no %complete feedback
 
+- try:
+
+	vips gaussnoise r.v 64 64 
+	vips gaussnoise g.v 64 64 
+	vips gaussnoise b.v 64 64 
+	vips bandjoin "r.v g.v b.v" out.png
+
+  out.png is monochrome for the first line of tiles ... do we need to seed the
+  generator?
+
 - why don't we get gtk-doc expansions in the leading chapters? we turn them on
 
-- need a thing to test C++ overloads 
+- can we generate python docstrings?
+
+  when we make a __getattr__ object, make it respond to __doc__
 
 - test other arg types
 

doc/reference/using-python.xml

@@ -134,8 +134,12 @@ from gi.repository import Vips
 
       <itemizedlist>
         <listitem>
+          <para><emphasis>
+            Automatic wrapping of vips operations
+          </emphasis> </para>
+
           <para>
-            Automatic wrapping of vips operations. It intercepts member lookup 
+            It intercepts member lookup 
             on the <code>Vips.Image</code> class and looks for vips operations
             with that name. So the vips operation "add", which appears in the 
             C API as vips_add(), appears in Python as 
@@ -174,8 +178,9 @@ min_value, x_pos, y_pos = im.min(x = True, y = True)
         </listitem>
 
         <listitem>
+          <para><emphasis>Automatic type conversion</emphasis></para>
           <para>
-            Automatic type conversion. The override looks at the type of 
+            The override looks at the type of 
             argument required by the operation and converts the value you 
             supply, when it can. For example, "linear" takes a 
             #VipsArrayDouble as an argument for the constant to use for 
@@ -184,16 +189,120 @@ min_value, x_pos, y_pos = im.min(x = True, y = True)
           </para>
 
           <para>
-            It does a couple of more ambitious conversions. If an operation 
+            It does a couple of more ambitious conversions. It will 
+            automatically convert to and from the various vips types, 
+            like #VipsBlob and #VipsArrayImage. For example, you can read the
+            ICC profile out of an image like this:
+
+<programlisting language="Python">
+profile = im.get_value("icc-profile-data")
+</programlisting>
+
+            and <code>profile</code> will be a string. 
+          </para>
+
+          <para>
+            If an operation 
             takes several input images, you can use a constant for all but 
             one of them and the wrapper will make a constant image for you. 
-            For example, <code>.bandjoin()</code> 
+            For example, <code>.ifthenelse()</code> uses a condition image to 
+            pick pixels between a then and an else image: 
+
+<programlisting language="Python">
+result_image = condition_image.ifthenelse(then_image, else_image)
+</programlisting>
+
+            You can use a constant instead of either the then or the else 
+            parts, and it will be expanded to an image for you. If you use a 
+            constant for both then and else, it will be expanded to match the 
+            condition image. For example:
+
+<programlisting language="Python">
+result_image = condition_image.ifthenelse([0, 255, 0], [255, 0, 0])
+</programlisting>
+
+            Will make an image where true pixels are green and false pixels 
+            are red.
+          </para>
+
+          <para>
+            This is useful for <code>.bandjoin()</code>, the thing to join 
+            two, or a set of images up bandwise. You can write:
+
+<programlisting language="Python">
+rgba = rgb.bandjoin(255)
+</programlisting>
+      
+            to add a constant 255 band to an image, perhaps to add an alpha 
+            channel. Of course you can also write:
+
+<programlisting language="Python">
+result_image = image1.bandjoin(image2)
+result_image = image1.bandjoin([image2, image3])
+result_image = Vips.Image.bandjoin([image1, image2, image3])
+result_image = image1.bandjoin([image2, 255])
+</programlisting>
+      
+            and so on. 
           </para>
         </listitem>
+
+        <listitem>
+          <para><emphasis>Exceptions</emphasis></para>
+          
+          <para>
+            The wrapper spots errors from vips operations and raises the 
+            <code>Vips.Error</code> exception. You can catch it in the 
+            usual way. 
+          </para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis>Overloads</emphasis></para>
+
+          <para>
+            The wrapper defines the usual set of arithmetic, boolean and 
+            relation overloads on 
+            <code>image</code>. You can mix images, constants and lists of 
+            constants (almost) freely. 
+          </para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis>Expansions</emphasis></para>
+
+          <para>
+            Some vips operators take an enum to select an action, for example
+            <code>.math()</code> can be used to calculate sine of every pixel 
+            like this:
+
+<programlisting language="Python">
+result_image = image.math(Vips.OperationMath.SIN)
+</programlisting>
+
+            This is annoying, so the wrapper expands all these enums into 
+            separate members named after the enum. So you can write:
+
+<programlisting language="Python">
+result_image = image.sin()
+</programlisting>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis>Utility functions</emphasis></para>
+
+          <para>
+            The wrapper defines a few extra useful utility functions: 
+            <code>.get_value()</code>, <code>.set_value()</code>
+            <code>.bandsplit()</code>, <code>.maxpos()</code>
+            <code>.minpos()</code>.
+          </para>
+        </listitem>
+
       </itemizedlist>
     </para>
       
   </refsect1>
-    
 
 </refentry>

libvips/arithmetic/complex.c

@@ -932,6 +932,7 @@ vips_complexform_init( VipsComplexform *complexform )
  * @left: input image 
  * @right: input image 
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Compose two real images to make a complex image. If either @left or @right 
  * are #VIPS_FORMAT_DOUBLE, @out is #VIPS_FORMAT_DPCOMPLEX. Otherwise @out 

libvips/arithmetic/getpoint.c

@@ -177,6 +177,7 @@ vips_getpoint_init( VipsGetpoint *getpoint )
  * @n: length of output vector
  * @x: position to read
  * @y: position to read
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Reads a single pixel on an image. 
  *

libvips/arithmetic/multiply.c

@@ -187,6 +187,7 @@ vips_multiply_init( VipsMultiply *multiply )
  * @left: left-hand image
  * @right: right-hand image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * This operation calculates @left * @right and writes the result to @out. 
  *

libvips/arithmetic/sign.c

@@ -165,6 +165,7 @@ vips_sign_init( VipsSign *sign )
  * vips_sign:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Finds the unit vector in the direction of the pixel value. For non-complex
  * images, it returns a signed char image with values -1, 0, and 1 for negative,

libvips/colour/LCh2Lab.c

@@ -134,6 +134,7 @@ vips_LCh2Lab_init( VipsLCh2Lab *LCh2Lab )
  * vips_LCh2Lab:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to Lab.
  *

libvips/colour/LCh2UCS.c

@@ -220,6 +220,7 @@ vips_LCh2CMC_init( VipsLCh2CMC *LCh2CMC )
  * vips_LCh2CMC:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to CMC.
  *

libvips/colour/Lab2LCh.c

@@ -146,6 +146,7 @@ vips_Lab2LCh_init( VipsLab2LCh *Lab2LCh )
  * vips_Lab2LCh:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn Lab to LCh.
  *

libvips/colour/Lab2LabQ.c

@@ -160,6 +160,7 @@ vips_Lab2LabQ_init( VipsLab2LabQ *Lab2LabQ )
  * vips_Lab2LabQ:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a Lab three-band float image to LabQ (#IM_CODING_LABQ).
  *

libvips/colour/Lab2LabS.c

@@ -101,6 +101,7 @@ vips_Lab2LabS_init( VipsLab2LabS *Lab2LabS )
  * vips_Lab2LabS:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn Lab to LabS, signed 16-bit int fixed point.
  *

libvips/colour/LabQ2Lab.c

@@ -144,6 +144,7 @@ vips_LabQ2Lab_init( VipsLabQ2Lab *LabQ2Lab )
  * vips_LabQ2Lab:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#IM_CODING_LABQ) image to a three-band float image.
  *

libvips/colour/LabQ2LabS.c

@@ -124,6 +124,7 @@ vips_LabQ2LabS_init( VipsLabQ2LabS *LabQ2LabS )
  * vips_LabQ2LabS:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#IM_CODING_LABQ) image to a three-band short image.
  *

libvips/colour/LabQ2sRGB.c

@@ -476,6 +476,7 @@ vips_LabQ2sRGB_init( VipsLabQ2sRGB *LabQ2sRGB )
  * vips_LabQ2sRGB:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image.
  *

libvips/colour/LabS2Lab.c

@@ -99,6 +99,7 @@ vips_LabS2Lab_init( VipsLabS2Lab *LabS2Lab )
  * vips_LabS2Lab:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a LabS three-band signed short image to a three-band float image.
  *

libvips/colour/LabS2LabQ.c

@@ -148,6 +148,7 @@ vips_LabS2LabQ_init( VipsLabS2LabQ *LabS2LabQ )
  * vips_LabS2LabQ:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a LabS three-band signed short image to LabQ
  *

libvips/colour/UCS2LCh.c

@@ -281,6 +281,7 @@ vips_CMC2LCh_init( VipsCMC2LCh *CMC2LCh )
  * vips_CMC2LCh:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn LCh to CMC.
  *

libvips/colour/XYZ2Yxy.c

@@ -106,6 +106,7 @@ vips_XYZ2Yxy_init( VipsXYZ2Yxy *XYZ2Yxy )
  * vips_XYZ2Yxy:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to Yxy.
  *

libvips/colour/XYZ2scRGB.c

@@ -117,6 +117,7 @@ vips_XYZ2scRGB_init( VipsXYZ2scRGB *XYZ2scRGB )
  * vips_XYZ2scRGB:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to Yxy.
  *

libvips/colour/Yxy2XYZ.c

@@ -107,6 +107,7 @@ vips_Yxy2XYZ_init( VipsYxy2XYZ *Yxy2XYZ )
  * vips_Yxy2XYZ:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Turn XYZ to Yxy.
  *

libvips/colour/dE00.c

@@ -250,6 +250,7 @@ vips_dE00_init( VipsdE00 *dE00 )
  * @left: first input image
  * @right: second input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate dE 00.
  *

libvips/colour/dE76.c

@@ -128,6 +128,7 @@ vips_dE76_init( VipsdE76 *dE76 )
  * @left: first input image
  * @right: second input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate dE 76.
  *

libvips/colour/dECMC.c

@@ -76,6 +76,7 @@ vips_dECMC_init( VipsdECMC *dECMC )
  * @left: first input image
  * @right: second input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Calculate dE CMC. The input images are transformed to CMC colour space and
  * the euclidean distance between corresponding pixels calculated. 

libvips/colour/float2rad.c

@@ -223,6 +223,7 @@ vips_float2rad_init( VipsFloat2rad *float2rad )
  * vips_float2rad:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Convert a three-band float image to Radiance 32-bit packed format.
  *

libvips/colour/rad2float.c

@@ -210,6 +210,7 @@ vips_rad2float_init( VipsRad2float *rad2float )
  * vips_rad2float:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Unpack a RAD (#IM_CODING_RAD) image to a three-band float image.
  *

libvips/colour/sRGB2scRGB.c

@@ -178,6 +178,7 @@ vips_sRGB2scRGB_init( VipssRGB2scRGB *sRGB2scRGB )
  * vips_sRGB2scRGB:
  * @in: input image
  * @out: output image
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Convert an sRGB image to scRGB.
  *

libvips/convolution/convolution.c

@@ -69,7 +69,14 @@
  * @VIPS_PRECISION_APPROXIMATE: approximate integer output
  *
  * How accurate an operation should be. 
+ */
+
+/** 
+ * VipsCombine:
+ * @VIPS_COMBINE_MAX: take the maximum of the possible values
+ * @VIPS_COMBINE_SUM: sum all the values
  *
+ * How to combine values. 
  */
 
 G_DEFINE_ABSTRACT_TYPE( VipsConvolution, vips_convolution, 

libvips/create/Makefile.am

@@ -30,9 +30,7 @@ libcreate_la_SOURCES = \
 	black.c \
 	text.c \
 	gaussnoise.c \
-	im_benchmark.c \
 	sines.c \
-	zone.c \
+	zone.c 
-	other_dispatch.c
 
 AM_CPPFLAGS = -I${top_srcdir}/libvips/include @VIPS_CFLAGS@ @VIPS_INCLUDES@ 

libvips/create/mask_ideal.c

@@ -100,7 +100,7 @@ vips_mask_ideal_init( VipsMaskIdeal *ideal )
  * @out: output image
  * @width: image size
  * @height: image size
- * @frequency_cutoff: 
+ * @frequency_cutoff: threshold at which filter ends
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:

libvips/create/mask_ideal_ring.c

@@ -114,8 +114,8 @@ vips_mask_ideal_ring_init( VipsMaskIdealRing *ideal_ring )
  * @out: output image
  * @width: image size
  * @height: image size
- * @frequency_cutoff: 
+ * @frequency_cutoff: threshold at which filter ends
- * @ringwidth: ringwidth
+ * @ringwidth: ring width
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:

libvips/deprecated/Makefile.am

@@ -20,6 +20,7 @@ libdeprecated_la_SOURCES = \
 	im_zerox.c \
 	arith_dispatch.c \
 	hist_dispatch.c \
+	other_dispatch.c \
 	im_maxpos_avg.c \
 	wrapvips7.c \
 	lazy.c \
@@ -31,6 +32,7 @@ libdeprecated_la_SOURCES = \
 	cooc_funcs.c \
 	glds_funcs.c \
 	im_fav4.c \
+	im_benchmark.c \
 	im_gadd.c \
 	im_gaddim.c \
 	im_gradcor.c \

libvips/draw/draw_line.c

@@ -339,6 +339,7 @@ vips_draw_linev( VipsImage *image,
  * @y1: start of draw_line
  * @x2: end of draw_line
  * @y2: end of draw_line
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Draws a 1-pixel-wide line on an image. Subclass and override ::plot to draw
  * lines made of other objects. See vips_draw_line_mask(), for example.  
@@ -371,6 +372,7 @@ vips_draw_line( VipsImage *image,
  * @y1: start of draw_line
  * @x2: end of draw_line
  * @y2: end of draw_line
+ * @...: %NULL-terminated list of optional named arguments
  *
  * As vips_draw_line(), but just take a single double for @ink. 
  *

libvips/draw/draw_mask.c

@@ -364,10 +364,12 @@ vips_draw_maskv( VipsImage *image,
 /**
  * vips_draw_mask:
  * @image: image to draw on
- * @ink: value to draw
+ * @ink: (array length=n): value to draw
+ * @n: size of ink array
  * @mask: mask of 0/255 values showing where to plot
  * @x: draw mask here
  * @y: draw mask here
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Draw @mask on the image. @mask is a monochrome 8-bit image with 0/255
  * for transparent or @ink coloured points. Intermediate values blend the ink
@@ -401,6 +403,7 @@ vips_draw_mask( VipsImage *image,
  * @mask: mask of 0/255 values showing where to plot
  * @x: draw mask here
  * @y: draw mask here
+ * @...: %NULL-terminated list of optional named arguments
  *
  * As vips_draw_mask(), but just takes a single double for @ink. 
  *

libvips/draw/draw_smudge.c

@@ -235,6 +235,7 @@ vips_draw_smudge_init( VipsDrawSmudge *draw_smudge )
  * @top: point to paint
  * @width: area to paint
  * @height: area to paint
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Smudge a section of @image. Each pixel in the area @left, @top, @width,
  * @height is replaced by the average of the surrounding 3x3 pixels. 

libvips/foreign/rawload.c

@@ -158,13 +158,13 @@ vips_foreign_load_raw_init( VipsForeignLoadRaw *raw )
  * vips_rawload:
  * @filename: file to load
  * @out: output image
+ * @width: width of image in pixels
+ * @height: height of image in pixels
+ * @bands: number of image bands
  * @...: %NULL-terminated list of optional named arguments
  *
  * Optional arguments:
  *
- * @width: width of image in pixels
- * @height: height of image in pixels
- * @bands: number of image bands
  * @offset: offset in bytes from start of file
  *
  * This operation mmaps the file, setting @out so that access to that 

libvips/include/vips/arithmetic.h

@@ -121,6 +121,8 @@ typedef enum {
  * @VIPS_OPERATION_BOOLEAN_AND: &
  * @VIPS_OPERATION_BOOLEAN_OR: |
  * @VIPS_OPERATION_BOOLEAN_EOR: ^
+ * @VIPS_OPERATION_BOOLEAN_LSHIFT: >>
+ * @VIPS_OPERATION_BOOLEAN_RSHIFT: <<
  *
  * See also: vips_boolean().
  */

libvips/include/vips/generate.h

@@ -67,7 +67,7 @@ int vips_stop_many( void *seq, void *a, void *b );
 VipsImage **vips_allocate_input_array( VipsImage *out, ... )
 	__attribute__((sentinel));
 
-int vips_image_generate( VipsImage *im,
+int vips_image_generate( VipsImage *image,
 	VipsStartFn start_fn, VipsGenerateFn generate_fn, VipsStopFn stop_fn,
 	void *a, void *b
 );

libvips/include/vips/threadpool.h

@@ -129,7 +129,7 @@ int vips_threadpool_run( VipsImage *im,
 	VipsThreadpoolProgressFn progress,
 	void *a );
 void vips_get_tile_size( VipsImage *im, 
-	int *tile_width, int *tile_height, int *nlines );
+	int *tile_width, int *tile_height, int *n_lines );
 
 void vips_concurrency_set( int concurrency );
 int vips_concurrency_get( void );

libvips/iofuncs/generate.c

@@ -525,7 +525,7 @@ vips_start_many( VipsImage *out, void *a, void *b )
 
 /**
  * vips_allocate_input_array:
- * @image: free array when this image closes
+ * @out: free array when this image closes
  * @...: %NULL-terminated list of input images
  *
  * Convenience function --- make a %NULL-terminated array of input images.
@@ -536,7 +536,7 @@ vips_start_many( VipsImage *out, void *a, void *b )
  * Returns: %NULL-terminated array of images. Do not free the result.
  */
 VipsImage **
-vips_allocate_input_array( VipsImage *image, ... )
+vips_allocate_input_array( VipsImage *out, ... )
 {
 	va_list ap;
 	VipsImage **ar;
@@ -544,19 +544,19 @@ vips_allocate_input_array( VipsImage *image, ... )
 
 	/* Count input images.
 	 */
-	va_start( ap, image );
+	va_start( ap, out );
 	for( n = 0; va_arg( ap, VipsImage * ); n++ )
 		;
 	va_end( ap );
 
 	/* Allocate array.
 	 */
-	if( !(ar = VIPS_ARRAY( image, n + 1, VipsImage * )) )
+	if( !(ar = VIPS_ARRAY( out, n + 1, VipsImage * )) )
 		return( NULL );
 
 	/* Fill array.
 	 */
-	va_start( ap, image );
+	va_start( ap, out );
 	for( i = 0; i < n; i++ ) 
 		ar[i] = va_arg( ap, VipsImage * );
 	va_end( ap );
@@ -567,7 +567,7 @@ vips_allocate_input_array( VipsImage *image, ... )
 
 /**
  * VipsStartFn:
- * @image: image being calculated
+ * @out: image being calculated
  * @a: user data
  * @b: user data
  *
@@ -581,13 +581,14 @@ vips_allocate_input_array( VipsImage *image, ... )
 
 /**
  * VipsGenerateFn:
- * @region: #VipsRegion to fill
+ * @out: #VipsRegion to fill
  * @seq: sequence value
  * @a: user data
  * @b: user data
+ * @stop: set this to stop processing
  *
- * Fill @image->valid with pixels. @seq contains per-thread state, such as the
+ * Fill @out->valid with pixels. @seq contains per-thread state, such as the
- * input regions.
+ * input regions. Set @stop to %TRUE to stop processing. 
  *
  * See also: vips_image_generate(), vips_stop_many().
  *

libvips/iofuncs/operation.c

@@ -160,7 +160,8 @@
 /** 
  * VipsOperationFlags:
  * @VIPS_OPERATION_NONE: no flags
- * @VIPS_OPERATION_SEQUENTIAL: can work sequentially
+ * @VIPS_OPERATION_SEQUENTIAL: can work sequentially with a small buffer
+ * @VIPS_OPERATION_SEQUENTIAL_UNBUFFERED: can work sequentially with no buffer
  * @VIPS_OPERATION_NOCACHE: must not be cached
  * @VIPS_OPERATION_DEPRECATED: a compatibility thing
  *
@@ -831,15 +832,15 @@ vips_call_by_name( const char *operation_name,
 
 /**
  * vips_call:
- * @operation_name:
+ * @operation_name: name of operation to call
  * @...: required args, then a %NULL-terminated list of argument/value pairs
  *
- * vips_call() calls the named operation, passing in required arguments, and
+ * vips_call() calls the named operation, passing in required arguments and
  * then setting any optional ones from the remainder of the arguments as a set
  * of name/value pairs. 
  *
  * For example, vips_embed() takes six required arguments, @in, @out, @x, @y, 
- * @width, @height; and has two optional arguments, @extend and @background.
+ * @width, @height, and has two optional arguments, @extend and @background.
  * You can run it with vips_call() like this: 
  *
  * |[

libvips/iofuncs/type.c

@@ -1428,7 +1428,7 @@ vips_value_get_array_int( const GValue *value, int *n )
 /** 
  * vips_value_set_array_int:
  * @value: (out): %GValue to get from
- * @array: (array length=n) (allow_none): array of ints
+ * @array: (array length=n) (allow-none): array of ints
  * @n: the number of elements 
  *
  * Set @value to hold a copy of @array. Pass in the array length in @n. 

libvips/resample/shrink.c

@@ -435,6 +435,7 @@ vips_shrink_init( VipsShrink *shrink )
  * @out: output image
  * @xshrink: horizontal shrink
  * @yshrink: vertical shrink
+ * @...: %NULL-terminated list of optional named arguments
  *
  * Shrink @in by a pair of factors with a simple box filter. 
  *