doc cleanups

libvips/deprecated/cimg_dispatch.c

@@ -37,16 +37,6 @@
 
 #include <vips/vips.h>
 
-/** 
- * SECTION: cimg_funcs
- * @short_description: expose operations from the CImg library, mostly noise
- * removal
- * @stability: Stable
- * @include: vips/vips.h
- *
- * The GREYCstoration filter.
- */
-
 static int
 greyc_vec( im_object *argv )
 {

libvips/deprecated/format.c

@@ -38,188 +38,6 @@
 #include <vips/vips.h>
 #include <vips/internal.h>
 
-/**
- * SECTION: format
- * @short_description: load and save in a variety of formats
- * @stability: Stable
- * @see_also: <link linkend="libvips-image">image</link>
- * @include: vips/vips.h
- *
- * VIPS has a simple system for representing image load and save operations in
- * a generic way.
- * You can ask for a loader for a certain file or select a saver based on a
- * filename. Once you have found a format, you can use it to load a file of
- * that type, save an image to a file of that type, query files for their type
- * and fields, and ask for supported features. You can also call the
- * converters directly, if you like. 
- *
- * If you define a new format, support for
- * it automatically appears in all VIPS user-interfaces. It will also be
- * transparently supported by im_open().
- *
- * VIPS comes with VipsFormat for TIFF, JPEG, PNG, Analyze, PPM, OpenEXR, CSV,
- * Matlab, Radiance, RAW, VIPS and ones that wrap libMagick and OpenSlide.
- */
-
-/**
- * VipsFormatFlags: 
- * @VIPS_FORMAT_NONE: no flags set
- * @VIPS_FORMAT_PARTIAL: the image may be read lazilly
- * @VIPS_FORMAT_BIGENDIAN: image pixels are most-significant byte first
- *
- * 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. 
- *
- * @VIPS_FORMAT_BIGENDIAN means that image pixels are most-significant byte
- * first. Depending on the native byte order of the host machine, you may
- * need to swap bytes. See im_copy_swap().
- */
-
-/**
- * VipsFormat:
- *
- * Actually, we never make %VipsFormat objects, we just use virtual methods on
- * the class object. It is defined as:
- *
- * |[
- * typedef struct _VipsFormatClass {
- *   VipsObjectClass parent_class;
- *
- *   gboolean (*is_a)( const char *filename );
- *   int (*header)( const char *filename, IMAGE *out );
- *   int (*load)( const char *filename, IMAGE *out );
- *   int (*save)( IMAGE *in, const char *filename );
- *   VipsFormatFlags (*get_flags)( const char *filename );
- *   int priority;
- *   const char **suffs;
- * } VipsFormatClass;
- * ]|
- *
- * Add a new format to VIPS by subclassing VipsFormat. Subclasses need to 
- * implement at least load() or save(). 
- *
- * These members are:
- *
- * <itemizedlist>
- *   <listitem>
- *     <para>
- * is_a() This function should return %TRUE if the file 
- * contains an image of this type. If you don't define this function, VIPS
- * will use the list of suffixes you supply instead.
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * header() This function should load the image header,
- * but not load any pixel data. If you don't define it, VIPS will use your
- * load() method instead. Return 0 for success, -1 for error, setting
- * im_error().
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * load() This function should load the image, or perhaps use im_generate() to
- * attach something to load sections of the image on demand. 
- * Users can embed
- * load options in the filename, see (for example) im_jpeg2vips().
- * If you don't
- * define this method, you can still define save() and have a save-only
- * format.
- * Return 0 for success, -1 for error, setting
- * im_error().
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * save() This function should save the image to the file. 
- * Users can embed
- * save options in the filename, see (for example) im_vips2tiff().
- * If you don't
- * define this method, you can still define load() and have a load-only
- * format.
- * Return 0 for success, -1 for error, setting
- * im_error().
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * get_flags() This function should return a hint about the properties of this
- * loader on this file. If you don't define it, users will always see '0', or
- * no flags. 
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * <structfield>priority</structfield> Where this format should fit in this 
- * list of
- * supported formats. 0 is a sensible value for most formats. Set a negative
- * value if you want to be lower on the list, positive to move up.
- *     </para>
- *   </listitem>
- *   <listitem>
- *     <para>
- * <structfield>suffs</structfield> A %NULL-terminated list of possible file 
- * name
- * suffixes, for example:
- * |[
- * static const char *tiff_suffs[] = { ".tif", ".tiff", NULL };
- * ]|
- * The suffix list is used to select a format to save a file in, and to pick a
- * loader if you don't define is_a().
- *     </para>
- *   </listitem>
- * </itemizedlist>
- *
- * You should also define <structfield>nickname</structfield> and
- * <structfield>description</structfield> in #VipsObject. 
- *
- * At the command-line, use:
- *
- * |[
- * vips --list classes | grep Format
- * ]|
- *
- * To see a list of all the supported formats.
- *
- * For example, the TIFF format is defined like this:
- *
-|[
-typedef VipsFormat VipsFormatTiff;
-typedef VipsFormatClass VipsFormatTiffClass;
-
-static void
-vips_format_tiff_class_init( VipsFormatTiffClass *class )
-{
-	VipsObjectClass *object_class = (VipsObjectClass *) class;
-	VipsFormatClass *format_class = (VipsFormatClass *) class;
-
-	object_class->nickname = "tiff";
-	object_class->description = _( "TIFF" );
-
-	format_class->is_a = istiff;
-	format_class->header = tiff2vips_header;
-	format_class->load = im_tiff2vips;
-	format_class->save = im_vips2tiff;
-	format_class->get_flags = tiff_flags;
-	format_class->suffs = tiff_suffs;
-}
-
-static void
-vips_format_tiff_init( VipsFormatTiff *object )
-{
-}
-
-G_DEFINE_TYPE( VipsFormatTiff, vips_format_tiff, VIPS_TYPE_FORMAT );
-]|
- *
- * Then call vips_format_tiff_get_type() somewhere in your init code to link
- * the format into VIPS (though of course the tiff format is linked in for you
- * already).
- *
- */
-
 /* To iterate over supported formats, we build a temp list of subclasses of 
  * VipsFormat, sort by priority, iterate, and free.
  */

libvips/deprecated/hist_dispatch.c

@@ -39,30 +39,6 @@
 
 #include <vips/vips.h>
 
-/**
- * SECTION: histograms_lut
- * @short_description: find, manipulate and apply histograms and lookup tables
- * @stability: Stable
- * @see_also: <link linkend="libvips-image">image</link>
- * @include: vips/vips.h
- *
- * Histograms and look-up tables are 1xn or nx1 images, where n is less than
- * 256 or less than 65536, corresponding to 8- and 16-bit unsigned int images. 
- * They are
- * tagged with a #VipsType of IM_TYPE_HISTOGRAM and usually displayed by
- * user-interfaces such as nip2 as plots rather than images.
- *
- * These functions can be broadly grouped as things to find or build 
- * histograms (im_histgr(), im_buildlut(), in_identity()), operations that 
- * manipulate histograms in some way (im_histcum(), im_histnorm()), operations
- * to apply histograms (im_maplut()), and a variety of utility 
- * operations.
- *
- * A final group of operations build tone curves. These are useful in
- * pre-press work for adjusting the appearance of images. They are designed
- * for CIELAB images, but might be useful elsewhere.
- */
-
 /* One image in, one out.
  */
 static im_arg_desc one_in_one_out[] = {

libvips/deprecated/other_dispatch.c

@@ -39,18 +39,6 @@
 
 #include <vips/vips.h>
 
-/** 
- * SECTION: other
- * @short_description: miscellaneous operators
- * @stability: Stable
- * @include: vips/vips.h
- *
- * These functions generate various test images. You can combine them with
- * the arithmetic and rotate functions to build more complicated images.
- *
- * The im_benchmark() operations are for testing the VIPS SMP system.
- */
-
 /* Args for im_sines.
  */
 static im_arg_desc sines_args[] = {

libvips/deprecated/resample_dispatch.c

@@ -41,16 +41,6 @@
 #include <vips/internal.h>
 #include <vips/transform.h>
 
-/** 
- * SECTION: resample
- * @short_description: shrink, expand, rotate with a choice of interpolators
- * @stability: Stable
- * @include: vips/vips.h
- *
- * Resample an image in various ways, using a #VipsInterpolate to generate
- * intermediate values.
- */
-
 /* Args to im_rightshift_size.
  */
 static im_arg_desc rightshift_size_args[] = {

libvips/deprecated/rw_mask.c

@@ -96,20 +96,6 @@
 
 #include <vips/vips.h>
 
-/**
- * SECTION: mask
- * @short_description: load, save and process mask (matrix) objects
- * @stability: Stable
- * @include: vips/vips.h
- *
- * These operations load, save and process mask objects. Masks are used as
- * paramaters to convolution and morphology operators, and to represent
- * matrices. There are two types of matrix: integer #INTMASK and double 
- * precision floating point #DOUBLEMASK.
- *
- * This API is horrible and clunky. Surely it will be replaced soon.
- */
-
 /**
  * INTMASK:
  * @xsize: mask width

libvips/draw/draw_line.c

@@ -341,8 +341,7 @@ vips_draw_linev( VipsImage *image,
  * @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
+ * Draws a 1-pixel-wide line on an image. 
- * lines made of other objects. See vips_draw_line_mask(), for example.  
  *
  * @ink is an array of double containing values to draw. 
  *

libvips/foreign/foreign.c

@@ -2032,7 +2032,7 @@ vips_tiffsave( VipsImage *in, const char *filename, ... )
  * Example:
  *
  * |[
- * vips_jpegload( "fred.jpg", &out,
+ * vips_jpegload( "fred.jpg", &out,
  * 	"shrink", 8,
  * 	"fail", TRUE,
  * 	NULL );

libvips/include/vips/foreign.h

@@ -239,6 +239,7 @@ gboolean vips_foreign_is_a_buffer( const char *loader, void *data, size_t size )
  * VipsSaveable:
  * @VIPS_SAVEABLE_MONO: 1 band (eg. CSV)
  * @VIPS_SAVEABLE_RGB: 1 or 3 bands (eg. PPM) 
+ * @VIPS_SAVEABLE_RGBA: 1, 2, 3 or 4 bands (eg. PNG)
  * @VIPS_SAVEABLE_RGBA_ONLY: 3 or 4 bands (eg. WEBP)
  * @VIPS_SAVEABLE_RGB_CMYK: 1, 3 or 4 bands (eg. JPEG)
  * @VIPS_SAVEABLE_ANY: any number of bands (eg. TIFF)

libvips/iofuncs/buf.c

@@ -63,13 +63,13 @@
  * VipsBuf buf = VIPS_BUF_STATIC (txt);
  * int i;
  *
- * vips_buf_appends (&buf, "Numbers are: ");
+ * vips_buf_appends (&buf, "Numbers are: ");
- * for (i = 0; i < array_length; i++) {
+ * for (i = 0; i &lt; array_length; i++) {
- *   if (i > 0)
+ *   if (i &gt; 0)
- *     vips_buf_appends (&buf, ", ");
+ *     vips_buf_appends (&amp;buf, ", ");
- *   vips_buf_appendg (&buf, array[i]);
+ *   vips_buf_appendg (&amp;buf, array[i]);
  * }
- * printf ("%s", vips_buf_all (&buf));
+ * printf ("%s", vips_buf_all (&amp;buf));
  * ]|
  */
 
@@ -175,7 +175,7 @@ vips_buf_set_static( VipsBuf *buf, char *base, int mx )
  * char txt[256];
  * VipsBuf buf;
  * 
- * vips_buf_init_static (&buf, txt, 256);
+ * vips_buf_init_static (&amp;buf, txt, 256);
  * ]|
  * 
  * Static buffers don't need to be freed when they go out of scope, but their
@@ -231,7 +231,7 @@ vips_buf_set_dynamic( VipsBuf *buf, int mx )
  * |[
  * VipsBuf buf;
  * 
- * vips_buf_init_synamic (&buf, 256);
+ * vips_buf_init_synamic (&amp;buf, 256);
  * ]|
  *
  * Dynamic buffers must be freed with vips_buf_destroy(), but their size can

libvips/iofuncs/error.c

@@ -94,7 +94,7 @@
  *   // vips_image_new_from_file() will set a message, we don't need to
  *   return( -1 );
  *
- * if( vips_image_get_width( im ) < 100 ) {
+ * if( vips_image_get_width( im ) &lt; 100 ) {
  *   // we have detected an error, we must set a message
  *   vips_error( "myprogram", "%s", _( "width too small" ) );
  *   return( -1 );

libvips/iofuncs/gate.c

@@ -86,7 +86,7 @@ static FILE *vips__thread_fp = NULL;;
 
 /**
  * vips_profile_set:
- * @info: %TRUE to enable profile recording
+ * @profile: %TRUE to enable profile recording
  *
  * If set, vips will record profiling information, and dump it on program
  * exit. These profiles can be analysed with the `vipsprofile` program. 

libvips/iofuncs/header.c

@@ -817,10 +817,10 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
  * |[
  * GValue value = { 0 };
  *
- * g_value_init (&value, G_TYPE_INT);
+ * g_value_init (&value, G_TYPE_INT);
- * g_value_set_int (&value, 42);
+ * g_value_set_int (&value, 42);
- * vips_image_set (image, field, &value);
+ * vips_image_set (image, field, &value);
- * g_value_unset (&value);
+ * g_value_unset (&value);
  * ]|
  *
  * See also: vips_image_get().
@@ -859,20 +859,20 @@ vips_image_set( VipsImage *image, const char *field, GValue *value )
  * GValue value = { 0 };
  * double d;
  *
- * if (vips_image_get (image, field, &value))
+ * if (vips_image_get (image, field, &value))
  *   return -1;
  *
- * if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
+ * if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
  *   vips_error( "mydomain", 
  *     _("field \"%s\" is of type %s, not double"),
  *     field, 
- *     g_type_name (G_VALUE_TYPE (&value)));
+ *     g_type_name (G_VALUE_TYPE (&value)));
- *   g_value_unset (&value);
+ *   g_value_unset (&value);
  *   return -1;
  * }
  *
- * d = g_value_get_double (&value);
+ * d = g_value_get_double (&value);
- * g_value_unset (&value);
+ * g_value_unset (&value);
  * ]|
  *
  * See also: vips_image_get_typeof(), vips_image_get_double().

libvips/iofuncs/image.c

@@ -383,7 +383,7 @@ G_DEFINE_TYPE( VipsImage, vips_image, VIPS_TYPE_OBJECT );
 
 /**
  * vips_progress_set:
- * @info: %TRUE to enable progress messages
+ * @progress: %TRUE to enable progress messages
  *
  * If set, vips will print messages about the progress of computation to
  * stdout. This can also be enabled with the --vips-progress option, or by

libvips/iofuncs/object.c

@@ -2213,7 +2213,7 @@ vips_object_set_valist( VipsObject *object, va_list ap )
  * |[
  * vips_object_set (operation,
  *   "input", in,
- *   "output", &out,
+ *   "output", &out,
  *   NULL);
  * ]|
  *
@@ -2853,9 +2853,9 @@ vips_object_local_array_cb( GObject *parent, VipsObjectLocal *local )
  *
  * t = vips_object_local_array( a, 5 );
  * if( 
- *   vips_add( a, b, &t[0], NULL ) ||
+ *   vips_add( a, b, &t[0], NULL ) ||
- *   vips_invert( t[0], &t[1], NULL ) ||
+ *   vips_invert( t[0], &t[1], NULL ) ||
- *   vips_add( t[1], t[0], &t[2], NULL ) ||
+ *   vips_add( t[1], t[0], &t[2], NULL ) ||
  *   vips_costra( t[2], out, NULL ) )
  *   return( -1 );
  * ]|

libvips/iofuncs/operation.c

@@ -102,7 +102,7 @@
  * VipsImage *im = ...;
  * VipsImage *t1; 
  *
- * if (vips_invert (im, &t1, NULL)) 
+ * if (vips_invert (im, &t1, NULL)) 
  *   error ..
  * ]|
  *
@@ -122,13 +122,13 @@
  * VipsImage *im = ...;
  * VipsImage *t1, *t2;
  *
- * if (vips_invert (im, &t1, NULL)) {
+ * if (vips_invert (im, &t1, NULL)) {
  *   g_object_unref (im);
  *   return -1;
  * }
  * g_object_unref (im);
  *
- * if (vips_flip (t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
+ * if (vips_flip (t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
  *   g_object_unref (t1);
  *   return -1;
  * }
@@ -143,8 +143,8 @@
  * VipsImage *im = ...;
  * VipsImage *t = (VipsImage **) vips_object_local_array (parent, 2);
  *
- * if (vips_invert (im, &t[0], NULL) ||
+ * if (vips_invert (im, &t[0], NULL) ||
- *   vips_flip (t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
+ *   vips_flip (t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
  *   return -1;
  * ]|
  *
@@ -933,7 +933,7 @@ vips_call_by_name( const char *operation_name,
  * VipsImage *in = ...
  * VipsImage *out;
  *
- * if( vips_call( "embed", in, &out, 10, 10, 100, 100,
+ * if( vips_call( "embed", in, &out, 10, 10, 100, 100,
  * 	"extend", VIPS_EXTEND_COPY,
  * 	NULL ) )
  * 	... error

libvips/iofuncs/region.c

@@ -825,7 +825,7 @@ vips_region_region( VipsRegion *reg,
  * Do two regions point to the same piece of image? ie. 
  *
  * |[
- * 	VIPS_REGION_ADDR( reg1, x, y ) == VIPS_REGION_ADDR( reg2, x, y ) &&
+ * 	VIPS_REGION_ADDR( reg1, x, y ) == VIPS_REGION_ADDR( reg2, x, y ) &&
  * 	*VIPS_REGION_ADDR( reg1, x, y ) == 
  * 		*VIPS_REGION_ADDR( reg2, x, y ) for all x, y, reg1, reg2.
  * ]|
@@ -1228,8 +1228,8 @@ vips_region_shrink_uncoded( VipsRegion *from, VipsRegion *to, VipsRect *target )
 
 /**
  * vips_region_shrink:
- * @reg: source region 
+ * @from: source region 
- * @dest: destination region 
+ * @to: destination region 
  * @target: #VipsRect of pixels you need to copy
  *
  * Write the pixels @target in @to from the x2 larger area in @from.

libvips/iofuncs/system.c

@@ -351,10 +351,10 @@ vips_system_init( VipsSystem *system )
  *
  * if (vips_system ("convert %s -swirl 45 %s",
  * 	"in", in, 
- * 	"out", &out, 
+ * 	"out", &out, 
  *   	"in_format", "%s.jpg", 
  *   	"out_format", "%s.jpg", 
- *   	"log", &log,
+ *   	"log", &log,
  *   	NULL))
  *   	error ...
  * ]|