improve docs

libvips/convolution/conv.c

@@ -182,17 +182,22 @@ vips_conv_init( VipsConv *conv )
  * Convolution. 
  *
  * Perform a convolution of @in with @mask.
- * Each output pixel is
- * calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale
- * and offset are part of @mask. 
+ * Each output pixel is calculated as:
+ *
+ * |[
+ * sigma[i]{pixel[i] * mask[i]} / scale + offset
+ * ]|
+ *
+ * where scale and offset are part of @mask. 
  *
  * If @precision is #VIPS_PRECISION_INTEGER then the convolution is performed
  * with integer arithmetic and the output image 
  * always has the same #VipsBandFormat as the input image. 
  *
- * Convolutions on unsigned 8-bit images are calculated with the 
- * processor's vector unit, if possible. Disable this with `--vips-novector` or 
- * `VIPS_NOVECTOR`.
+ * For #VIPS_FORMAT_UCHAR images, vips_conv() uses a fast vector path based on
+ * fixed-point arithmetic. This can produce slightly different results. 
+ * Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or
+ * vips_vector_set_enabled().
  *
  * If @precision is #VIPS_PRECISION_FLOAT then the convolution is performed
  * with floating-point arithmetic. The output image 

libvips/convolution/convi.c

@@ -1030,16 +1030,22 @@ vips_convi_init( VipsConvi *convi )
  * @mask: convolve with this mask
  * @...: %NULL-terminated list of optional named arguments
  *
- * Convolution. This is a low-level operation, see vips_conv() for something
- * more convenient. 
+ * Integer convolution. This is a low-level operation, see vips_conv() for 
+ * something more convenient. 
  *
- * Perform a convolution of @in with @mask.
- * Each output pixel is
- * calculated as rint(sigma[i]{pixel[i] * mask[i]} / scale) + offset, where 
- * scale and offset are part of @mask. 
+ * @mask is converted to an integer mask with rint() of each element, rint of
+ * scale and rint of offset. Each output pixel is then calculated as 
  *
- * The convolution is performed with integer arithmetic. The output image 
- * always has the same #VipsBandFormat as the input image. 
+ * |[
+ * sigma[i]{pixel[i] * mask[i]} / scale + offset
+ * ]|
+ *
+ * The output image always has the same #VipsBandFormat as the input image. 
+ *
+ * For #VIPS_FORMAT_UCHAR images, vips_convi() uses a fast vector path based on
+ * fixed-point arithmetic. This can produce slightly different results. 
+ * Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or
+ * vips_vector_set_enabled().
  *
  * See also: vips_conv().
  *

libvips/convolution/im_aconvsep.c

@@ -56,13 +56,13 @@
  */
 
 /* Show sample pixels as they are transformed.
-#define DEBUG_PIXELS
  */
+#define DEBUG_PIXELS
 
 /*
+ */
 #define DEBUG
 #define VIPS_DEBUG
- */
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>