doc improvements

libvips/iofuncs/image.c

@@ -63,9 +63,21 @@
  *
  * The image class and associated types and macros.
  *
- * vips_image_wio_input() and friends indicate the image IO style you
- * intend to use, transforming the underlying #VipsImage structure if
- * necessary.
+ * Images can be created from files on disc (with vips_image_new_from_file()),
+ * from formatted buffers held in memory (with vips_image_new_from_buffer()),
+ * and from C-style arrays held in memory (with vips_image_new_from_memory()).
+ *
+ * Use things like vips_invert() to manipulate your images. When you are done,
+ * you can write images to disc files (with vips_image_write_to_file()),
+ * to formatted memory buffers (with vips_image_write_to_buffer()) and to
+ * C-style memory arrays (with vips_image_write_to_memory().
+ *
+ * See <link linkend="VipsOperation">operation</link> for an introduction to
+ * running operations on images, see <link
+ * linkend="libvips-header">header</link> for getting and setting image
+ * metadata. See <link linkend="VipsObject">object</link> for a discussion of
+ * the lower levels. 
+ *
  */
 
 /**

libvips/iofuncs/object.c

@@ -73,12 +73,10 @@
  *
  * <emphasis>Run-time introspection</emphasis> Vips objects can be fully 
  * introspected at
- * run-time. There is not need for a separate source-code analysis. 
- *
- * <emphasis>Command-line interface</emphasis> Vips objects have an 
- * automatic command-line
- * line interface with a set of virtual methods. 
+ * run-time. There is not need for separate source-code analysis. 
  *
+ * <emphasis>Command-line interface</emphasis> Any vips object can be run from
+ * the command-line with the `vips` driver program. 
  */
 
 /** 

libvips/iofuncs/operation.c

@@ -61,7 +61,33 @@
  * libvips. 
  *
  * It also maintains a cache of recent operations. You can tune the cache
- * behaviour in various ways. 
+ * behaviour in various ways, see vips_cache_set_max() and friends. 
+ *
+ * Use vips_call() to call any vips operation from C. For example:
+ *
+ * |[
+ * VipsImage *in = ...
+ * VipsImaghe *out;
+ *
+ * if( vips_call( "embed", in, &out, 10, 10, 100, 100,
+ * 	"extend", VIPS_EXTEND_COPY,
+ * 	NULL ) )
+ * 	...
+ * ]|
+ *
+ * Will execute vips_embed() setting the optional `extend` property to
+ * #VIPS_EXTEND_COPY. 
+ *
+ * If you want to search for operations, see what arguments they need, and
+ * test argument properties, see
+ * <link linkend="libvips-object">object</link>. 
+ *
+ * vips_call_split() lets you run an operation with the optional and required
+ * arguments split into separate lists. vips_call_split_option_string() lets
+ * you set options from strings as well.
+ *
+ * Use vips_call_argv() to run any vips operation from a command-line style
+ * argc/argv array. 
  *
  */