[glib/ebassi/source-once: 3/3] gmain: Minor documentation updates to idle-once and timeout-once funcs

[Philip Withnall <pwithnall src gnome org>]

commit c1f94cd1a55c5b031bfc008fe45ea4bf0ebcbbeb
Author: Philip Withnall <pwithnall endlessos org>
Date:   Fri May 27 12:41:29 2022 +0100

    gmain: Minor documentation updates to idle-once and timeout-once funcs
    
    As suggested on !2684.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 glib/gmain.c | 39 +++++++--------------------------------
 glib/gmain.h |  3 ++-
 2 files changed, 9 insertions(+), 33 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index dd533c91d1..cd92ed580c 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -5184,34 +5184,15 @@ once_function (gpointer data)
  *   milliseconds (1/1000ths of a second)
  * @function: function to call
  * @data: data to pass to @function
- * 
+ *
  * Sets a function to be called after @interval milliseconds have elapsed,
  * with the default priority, %G_PRIORITY_DEFAULT.
  *
- * The given @function is called once.
- *
- * Note that timeout functions may be delayed, due to the processing of other
- * event sources. Thus they should not be relied on for precise timing.
- *
- * See [memory management of sources][mainloop-memory-management] for details
- * on how to handle the return value and memory management of @data.
+ * The given @function is called once and then the source will be automatically
+ * removed from the main context.
  *
- * If you want to have a timer in the "seconds" range and do not care
- * about the exact time of the first call of the timer, use the
- * g_timeout_add_seconds() function; this function allows for more
- * optimizations and more efficient system power usage.
+ * This function otherwise behaves like g_timeout_add().
  *
- * This internally creates a main loop source using g_timeout_source_new()
- * and attaches it to the global #GMainContext using g_source_attach(), so
- * the callback will be invoked in whichever thread is running that main
- * context. You can do these steps manually if you need greater control or to
- * use a custom main context.
- * 
- * It is safe to call this function from any thread.
- *
- * The interval given is in terms of monotonic time, not wall clock
- * time.  See g_get_monotonic_time().
- * 
  * Returns: the ID (greater than 0) of the event source
  *
  * Since: 2.74
@@ -6136,16 +6117,10 @@ g_idle_add (GSourceFunc    function,
  * events pending to the default main loop. The function is given the
  * default idle priority, %G_PRIORITY_DEFAULT_IDLE.
  *
- * The function will only be called once.
+ * The function will only be called once and then the source will be
+ * automatically removed from the main context.
  *
- * See [memory management of sources][mainloop-memory-management] for details
- * on how to handle the return value and memory management of @data.
- * 
- * This internally creates a main loop source using g_idle_source_new()
- * and attaches it to the global #GMainContext using g_source_attach(), so
- * the callback will be invoked in whichever thread is running that main
- * context. You can do these steps manually if you need greater control or to
- * use a custom main context.
+ * This function otherwise behaves like g_idle_add().
  *
  * Returns: the ID (greater than 0) of the event source
  *
diff --git a/glib/gmain.h b/glib/gmain.h
index aebf5cb233..ae3cc3ec55 100644
--- a/glib/gmain.h
+++ b/glib/gmain.h
@@ -199,7 +199,8 @@ typedef gboolean (*GSourceFunc)       (gpointer user_data);
  * @user_data: data passed to the function, set when the source was
  *   created
  *
- * A source function that is only called once.
+ * A source function that is only called once before being removed from the main
+ * context automatically.
  *
  * See: g_idle_add_once(), g_timeout_add_once()
  *