[gtk: 1/2] scrollable: Clarify when to set adjustment props

[Benjamin Otte <otte src gnome org>]

commit e2675306e1b7f92313e3e9c9dc930aa4d207db5e
Author: Ivan Molodetskikh <yalterz gmail com>
Date:   Mon Apr 11 10:31:52 2022 +0300

    scrollable: Clarify when to set adjustment props
    
    Instead of populating the properties right away (when the widget might
    not have been allocated yet, and hence cannot know the right values),
    the widget should queue an allocation, where it will populate the
    values.

 gtk/gtkscrollable.c | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
---
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.