[glib] gmain: Improve documentation of GSourceFuncs

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 7f639fd5a00d6f59f8d4e7cccd2964461e2b917e
Author: Michael Catanzaro <mcatanzaro igalia com>
Date:   Tue Nov 28 09:58:50 2017 -0600

    gmain: Improve documentation of GSourceFuncs
    
    We should more clearly indicate that a source ready time will result in
    a source being dispatched even if prepare and check never return TRUE.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=790948

 glib/gmain.c |    2 +-
 glib/gmain.h |   22 +++++++++++-----------
 2 files changed, 12 insertions(+), 12 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index 0f67c17..f30a6ab 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -1824,7 +1824,7 @@ g_source_get_priority (GSource *source)
  * Note that if you have a pair of sources where the ready time of one
  * suggests that it will be delivered first but the priority for the
  * other suggests that it would be delivered first, and the ready time
- * for both sources is reached during the same main context iteration
+ * for both sources is reached during the same main context iteration,
  * then the order of dispatch is undefined.
  *
  * It is a no-op to call this function on a #GSource which has already been
diff --git a/glib/gmain.h b/glib/gmain.h
index a7da20d..76e2c14 100644
--- a/glib/gmain.h
+++ b/glib/gmain.h
@@ -87,8 +87,8 @@ typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
  *     the @timeout_ values returned which were >= 0.  Since 2.36 this may
  *     be %NULL, in which case the effect is as if the function always returns
  *     %FALSE with a timeout of -1.  If @prepare returns a
- *     timeout and the source also has a 'ready time' set then the
- *     nearer of the two will be used.
+ *     timeout and the source also has a ready time set, then the
+ *     lower of the two will be used.
  * @check: Called after all the file descriptors are polled. The source
  *     should return %TRUE if it is ready to be dispatched. Note that some
  *     time may have passed since the previous prepare function was called,
@@ -96,17 +96,17 @@ typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
  *     be %NULL, in which case the effect is as if the function always returns
  *     %FALSE.
  * @dispatch: Called to dispatch the event source, after it has returned
- *     %TRUE in either its @prepare or its @check function. The @dispatch
- *     function is passed in a callback function and data. The callback
- *     function may be %NULL if the source was never connected to a callback
- *     using g_source_set_callback(). The @dispatch function should call the
- *     callback function with @user_data and whatever additional parameters
- *     are needed for this type of event source. The return value of the
- *     @dispatch function should be #G_SOURCE_REMOVE if the source should be
- *     removed or #G_SOURCE_CONTINUE to keep it.
+ *     %TRUE in either its @prepare or its @check function, or if a ready time
+ *     has been reached. The @dispatch function receives a callback function and
+ *     user data. The callback function may be %NULL if the source was never
+ *     connected to a callback using g_source_set_callback(). The @dispatch
+ *     function should call the callback function with @user_data and whatever
+ *     additional parameters are needed for this type of event source. The
+ *     return value of the @dispatch function should be #G_SOURCE_REMOVE if the
+ *     source should be removed or #G_SOURCE_CONTINUE to keep it.
  * @finalize: Called when the source is finalized. At this point, the source
  *     will have been destroyed, had its callback cleared, and have been removed
- *     from its #GMainContext, but it will still have its final reference count;
+ *     from its #GMainContext, but it will still have its final reference count,
  *     so methods can be called on it from within this function.
  *
  * The `GSourceFuncs` struct contains a table of