diff --git a/src/hb-cairo.cc b/src/hb-cairo.cc
index 3a2d36d59..b586c1245 100644
--- a/src/hb-cairo.cc
+++ b/src/hb-cairo.cc
@@ -785,6 +785,10 @@ hb_cairo_font_face_get_scale_factor (cairo_font_face_t *font_face)
  * See hb_cairo_font_face_set_scale_factor() for the details of
  * the @scale_factor argument.
  *
+ * The returned @glyphs vector actually has `@num_glyphs + 1` entries in
+ * it and the x,y values of the extra entry at the end add up the advance
+ * x,y of all the glyphs in the @buffer.
+ *
  * Since: REPLACEME
  */
 void