add callback gtkdoc

ChangeLog

@@ -53,6 +53,7 @@
 - gtk-doc comments for meta
 - gtk-doc comments for header
 - im_printlines(), im_debugim() deprecated (use im_vips2csv() instead)
+- callback gtkdocs
 
 25/3/09 started 7.18.0
 - revised version numbers

doc/reference/libvips-docs.sgml.in

@@ -19,6 +19,7 @@
     <title>Core VIPS API</title>
     <xi:include href="xml/image.xml"/>
     <xi:include href="xml/header.xml"/>
+    <xi:include href="xml/callback.xml"/>
     <xi:include href="xml/meta.xml"/>
     <xi:include href="xml/buf.xml"/>
   </chapter>

libvips/include/vips/Makefile.am

@@ -7,6 +7,7 @@ pkginclude_HEADERS = \
 	dispatch.h \
 	format.h \
 	header.h \
+	callback.h \
 	fmask.h \
 	mosaic.h \
 	interpolate.h \

libvips/include/vips/callback.h

@@ -0,0 +1,56 @@
+/* Various callbacks.
+ */
+
+/*
+
+    Copyright (C) 1991-2005 The National Gallery
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+ */
+
+/*
+
+    These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
+
+ */
+
+#ifndef IM_CALLBACK_H
+#define IM_CALLBACK_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif /*__cplusplus*/
+
+/* Also used for eg. im_local() and friends.
+ */
+typedef int (*im_callback_fn)( void *a, void *b );
+
+int im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
+int im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
+
+int im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
+int im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
+int im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b );
+
+int im_add_invalidate_callback( IMAGE *im, 
+	im_callback_fn fn, void *a, void *b );
+
+
+#ifdef __cplusplus
+}
+#endif /*__cplusplus*/
+
+#endif /*!IM_CALLBACK_H*/

libvips/include/vips/proto.h

@@ -146,13 +146,6 @@ int im_existsf( const char *name, ... )
 	__attribute__((format(printf, 1, 2)));
 int im_isvips( const char * );
 
-int im_add_close_callback( IMAGE *, im_callback_fn, void *, void * );
-int im_add_preclose_callback( IMAGE *, im_callback_fn, void *, void * );
-int im_add_evalstart_callback( IMAGE *, im_callback_fn, void *, void * );
-int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * );
-int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * );
-int im_add_invalidate_callback( IMAGE *, im_callback_fn, void *, void * );
-
 void error_exit( const char *, ... )
 	__attribute__((noreturn, format(printf, 1, 2)));
 const char *im_error_buffer( void );

libvips/include/vips/util.h

@@ -181,7 +181,6 @@ extern "C" {
 
 /* Basic function types.
  */
-typedef int (*im_callback_fn)( void *, void * );
 typedef void *(*im_construct_fn)( void *, void *, void * );
 
 /* strtok replacement.

libvips/include/vips/vips.h

@@ -124,6 +124,7 @@ typedef struct im__DOUBLEMASK {
 
 #include <vips/image.h>
 #include <vips/almostdeprecated.h>
+#include <vips/callback.h>
 #include <vips/util.h>
 #include <vips/colour.h>
 /* #include <vips/vector.h> */

libvips/iofuncs/callback.c

@@ -54,13 +54,28 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * SECTION: callback
+ * @short_description: image callbacks
+ * @stability: Stable
+ * @see_also: <link linkend="libvips-image">image</link>
+ * @include: vips/vips.h
+ *
+ * Images trigger various callbacks at various points in their lifetime. You
+ * can register callbacks and be notified of various events, such as
+ * evaluation progress or close.
+ *
+ * Callbacks should return 0 for success, or -1 on error, setting an error
+ * message with im_error().
+ */
+
 /* Callback struct. We attach a list of callbacks to images to be invoked when
  * the image is closed. These do things like closing previous elements in a
  * chain of operations, freeing client data, etc.
  */
 typedef struct {
 	IMAGE *im;		/* IMAGE we are attached to */
-	int (*fn)();		/* callback function */
+	im_callback_fn fn;	/* callback function */
 	void *a, *b;		/* arguments to callback */
 } VCallback;
 
@@ -68,7 +83,7 @@ typedef struct {
  * im__close(), or by im_generate(), etc. for evalend callbacks.
  */
 static int
-add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b )
+add_callback( IMAGE *im, GSList **cblist, im_callback_fn fn, void *a, void *b )
 {	
 	VCallback *cbs;
 
@@ -84,23 +99,81 @@ add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b )
 	return( 0 );
 }
 
+/**
+ * im_add_close_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches a close callback @fn to @im.
+ *
+ * Close callbacks are triggered exactly once when the image has been closed
+ * and most resources freed, but just before the memory for @im is released.
+ *
+ * Close callbacks are a good place to free memory that was need to generate
+ * @im, delete temporary files and so on. You can close other images and there
+ * may even be circularity in your close lists.
+ *
+ * See also: im_malloc() (implemented with im_add_close_callback()),
+ * im_add_preclose_callback() (called earlier in the image close process),
+ * im_free().
+ */
 int
-im_add_close_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {	
 	return( add_callback( im, &im->closefns, fn, a, b ) );
 }
 
+/**
+ * im_add_preclose_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches a pre-close callback @fn to @im.
+ *
+ * Pre-close callbacks are triggered exactly once just before an image is
+ * closed. The image is still valid and you can do anything with it, except
+ * stop close from happening.
+ *
+ * Pre-close callbacks are a good place for languae bindings to break as
+ * association between the language object and the VIPS image.
+ */
 int
-im_add_preclose_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {	
 	return( add_callback( im, &im->preclosefns, fn, a, b ) );
 }
 
-/* Add an eval callback to an IMAGE. You must call this after opening the
+/**
- * image but before using it as an argument to an operation.
+ * im_add_eval_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches an eval callback @fn to @im.
+ *
+ * Eval callbacks are called during evaluation and are a good place to give
+ * the user feedback about computation progress. In the eval callback, you may
+ * look at the #VipsProgress #time member of #IMAGE to get information about 
+ * the number of
+ * pels processed, elapsed time, and so on.
+ *
+ * Eval callbacks are inherited. That is, any images which use your  image
+ * as  input  will inherit your eval callbacks. As a result, if you add an
+ * eval callback to an image, you will be notified if any later image uses
+ * your image for computation.
+ *
+ * If  a  later image adds eval callbacks, then the inheritance is broken,
+ * and that image will recieve notification instead.
+ *
+ * See also: im_add_evalend_callback(), im_add_evalstart_callback().
  */
 int
-im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {
 	/* Mark this image as needing progress feedback. im__link_make()
 	 * propogates this value to our children as we build a pipeline.
@@ -111,20 +184,86 @@ im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b )
 	return( add_callback( im, &im->evalfns, fn, a, b ) );
 }
 
+/**
+ * im_add_evalend_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches an eval end callback @fn to @im.
+ *
+ * Eval end callbacks are called at the end of evaluation. They are a good
+ * place to clean up after progress notification or to display some
+ * diagnostics about computation (eg. an overflow count). They can be called 
+ * many times. Every evalend call is guaranteed to have a matching evalstart,
+ * but not necessarily any eval calls.
+ *
+ * Eval callbacks are inherited. That is, any images which use your  image
+ * as  input  will inherit your eval callbacks. As a result, if you add an
+ * eval callback to an image, you will be notified if any later image uses
+ * your image for computation.
+ *
+ * If  a  later image adds eval callbacks, then the inheritance is broken,
+ * and that image will recieve notification instead.
+ *
+ * See also: im_add_eval_callback(), im_add_evalstart_callback().
+ */
 int
-im_add_evalend_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {	
 	return( add_callback( im, &im->evalendfns, fn, a, b ) );
 }
 
+/**
+ * im_add_evalstart_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches an eval start callback @fn to @im.
+ *
+ * Eval start callbacks are called at the beginning of evaluation. They are a 
+ * good
+ * place to get ready to give progress notification.
+ * They can be called 
+ * many times. Every evalend call is guaranteed to have a matching evalstart,
+ * but not necessarily any eval calls.
+ *
+ * Eval callbacks are inherited. That is, any images which use your  image
+ * as  input  will inherit your eval callbacks. As a result, if you add an
+ * eval callback to an image, you will be notified if any later image uses
+ * your image for computation.
+ *
+ * If  a  later image adds eval callbacks, then the inheritance is broken,
+ * and that image will recieve notification instead.
+ *
+ * See also: im_add_eval_callback(), im_add_evalend_callback().
+ */
 int
-im_add_evalstart_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {	
 	return( add_callback( im, &im->evalstartfns, fn, a, b ) );
 }
 
+/**
+ * im_add_invalidate_callback:
+ * @im: image to attach callback to
+ * @fn: callback function
+ * @a: user data 1
+ * @b: user data 2
+ *
+ * Attaches an invalidate callback @fn to @im.
+ *
+ * Invalidate callbacks are triggered
+ * when VIPS invalidates the cache on an image. This is useful for
+ * removing images from other, higher-level caches.
+ *
+ * See also: im_invalidate().
+ */
 int
-im_add_invalidate_callback( IMAGE *im, int (*fn)(), void *a, void *b )
+im_add_invalidate_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
 {	
 	return( add_callback( im, &im->invalidatefns, fn, a, b ) );
 }

libvips/iofuncs/meta.c

@@ -86,7 +86,7 @@
  * SECTION: meta
  * @short_description: get and set image metadata
  * @stability: Stable
- * @see_also: header
+ * @see_also: <link linkend="libvips-header">header</link>
  * @include: vips/vips.h
  *
  * You can attach arbitrary metadata to images. Metadata is copied as images