diff --git a/libvips/resample/affine.c b/libvips/resample/affine.c
index bbc1a176..564e159a 100644
--- a/libvips/resample/affine.c
+++ b/libvips/resample/affine.c
@@ -665,7 +665,10 @@ vips_affine_init( VipsAffine *affine )
  *
  * @idx, @idy, @odx, @ody default to zero.
  *
- * See also: vips_shrink(), #VipsInterpolate.
+ * This operation does not change xres or yres. The image resolution needs to
+ * be updated by the application. 
+ *
+ * See also: vips_shrink(), vips_resize(), #VipsInterpolate.
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/resample/resize.c b/libvips/resample/resize.c
index 8f0d5b80..a28d1ed1 100644
--- a/libvips/resample/resize.c
+++ b/libvips/resample/resize.c
@@ -281,10 +281,13 @@ vips_resize_init( VipsResize *resize )
  * then resampled with vips_affine() and the supplied interpolator, then
  * sharpened. 
  *
- * @interpolate defaults to bicubic, or bilinear if that is not available. 
+ * @interpolate defaults to bicubic.
  *
  * @idx, @idy default to zero. Offset them by 0.5 to get pixel-centre sampling. 
  *
+ * This operation does not change xres or yres. The image resolution needs to
+ * be updated by the application. 
+ *
  * See also: vips_shrink(), vips_affine(), #VipsInterpolate.
  *
  * Returns: 0 on success, -1 on error
diff --git a/libvips/resample/shrink.c b/libvips/resample/shrink.c
index e8b7c091..1f690e12 100644
--- a/libvips/resample/shrink.c
+++ b/libvips/resample/shrink.c
@@ -442,9 +442,12 @@ vips_shrink_init( VipsShrink *shrink )
  * You will get aliasing for non-integer shrinks. In this case, shrink with
  * this function to the nearest integer size above the target shrink, then
  * downsample to the exact size with vips_affine() and your choice of
- * interpolator.
+ * interpolator. See vips_resize() for a convenient way to do this.
  *
- * See also: vips_affine().
+ * This operation does not change xres or yres. The image resolution needs to
+ * be updated by the application. 
+ *
+ * See also: vips_resize(), vips_affine().
  *
  * Returns: 0 on success, -1 on error
  */