[glib: 1/2] gmain: Expand documentation about GSource priorities a little

[Sebastian Dröge <sdroege src gnome org>]

commit 9ee583a387cb55d4997028065d09a84558bfeaaf
Author: Philip Withnall <pwithnall endlessos org>
Date:   Sun Feb 20 11:44:09 2022 +0000

    gmain: Expand documentation about GSource priorities a little
    
    Prompted by https://stackoverflow.com/q/71173668/2931197
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 glib/gmain.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index 068184866..0e757a6f6 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -124,10 +124,14 @@
  * Each event source is assigned a priority. The default priority,
  * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
  * Values greater than 0 denote lower priorities. Events from high priority
- * sources are always processed before events from lower priority sources.
+ * sources are always processed before events from lower priority sources: if
+ * several sources are ready to dispatch, the ones with equal-highest priority
+ * will be dispatched on the current #GMainContext iteration, and the rest wait
+ * until a subsequent #GMainContext iteration when they have the highest
+ * priority of the sources which are ready for dispatch.
  *
  * Idle functions can also be added, and assigned a priority. These will
- * be run whenever no events with a higher priority are ready to be processed.
+ * be run whenever no events with a higher priority are ready to be dispatched.
  *
  * The #GMainLoop data type represents a main event loop. A GMainLoop is
  * created with g_main_loop_new(). After adding the initial event sources,