diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c
index 041f09ac04..4df0c170f6 100644
--- a/gtk/gtkscrollable.c
+++ b/gtk/gtkscrollable.c
@@ -29,13 +29,11 @@
  * All scrollable widgets should do the following.
  *
  * - When a parent widget sets the scrollable child widget’s adjustments,
- *   the widget should populate the adjustments’
- *   [property@Gtk.Adjustment:lower],
- *   [property@Gtk.Adjustment:upper],
- *   [property@Gtk.Adjustment:step-increment],
- *   [property@Gtk.Adjustment:page-increment] and
- *   [property@Gtk.Adjustment:page-size] properties and connect to the
- *   [signal@Gtk.Adjustment::value-changed] signal.
+ *   the widget should connect to the [signal@Gtk.Adjustment::value-changed]
+ *   signal. The child widget should then populate the adjustments’ properties
+ *   as soon as possible, which usually means queueing an allocation right away
+ *   and populating the properties in the [vfunc@Gtk.Widget.size_allocate]
+ *   implementation.
  *
  * - Because its preferred size is the size for a fully expanded widget,
  *   the scrollable widget must be able to cope with underallocations.
@@ -43,7 +41,8 @@
  *   [vfunc@Gtk.Widget.size_allocate] implementation.
  *
  * - When the parent allocates space to the scrollable child widget,
- *   the widget should update the adjustments’ properties with new values.
+ *   the widget must ensure the adjustments’ property values are correct and up
+ *   to date, for example using [method@Gtk.Adjustment.configure].
  *
  * - When any of the adjustments emits the [signal@Gtk.Adjustment::value-changed]
  *   signal, the scrollable widget should scroll its contents.