add note about non-determinism in stats

added a note to the docs for max/min/stats about non-determinism in the
results if there are many maxima/minima

thanks Mark

libvips/arithmetic/max.c

@@ -510,6 +510,10 @@ vips_max_init( VipsMax *max )
  * @out_array, @x_array and @y_array. These values are returned sorted from 
  * largest to smallest.
  *
+ * If there are more than @size maxima, the maxima returned will be a random
+ * selection of the maxima in the image. Equal maxima will be returned in a
+ * random order.
+ *
  * See also: vips_min(), vips_stats().
  *
  * Returns: 0 on success, -1 on error

libvips/arithmetic/min.c

@@ -514,6 +514,10 @@ vips_min_init( VipsMin *min )
  * These values are returned sorted from 
  * smallest to largest.
  *
+ * If there are more than @size minima, the minima returned will be a random
+ * selection of the minima in the image. Equal minima will be returned in a
+ * random order.
+ *
  * See also: vips_min(), vips_stats().
  *
  * Returns: 0 on success, -1 on error

libvips/arithmetic/stats.c

@@ -445,6 +445,9 @@ vips_stats_init( VipsStats *stats )
  * Row 0 has statistics for all 
  * bands together, row 1 has stats for band 1, and so on.
  *
+ * If there is more than one maxima or minima, one of them will be chosen at 
+ * random. 
+ *
  * See also: vips_avg(), vips_min().
  *
  * Returns: 0 on success, -1 on error