[glib/wip/gtimeval-document-year-2038-problem] Document that GTimeVal is subject to the year 2038 problem on 32-bit systems

[Iain Lane <iainl src gnome org>]

commit 68a4e273b443ad79a3cd392d464390ab6a3fed2e
Author: Iain Lane <iainl gnome org>
Date:   Tue Sep 4 11:15:25 2018 +0100

    Document that GTimeVal is subject to the year 2038 problem on 32-bit systems
    
    It might not be immediately obvious that this is the case. Let's record
    it in the description of `GTimeVal` itself and also in
    `g_time_val_from_iso8601`.
    
    We also drop an incorrect statement in the documentation for
    `g_time_val_from_iso8601` stating that years up to 3000 were supported;
    this is also not true for the same reason.
    
    Related: #1509

 glib/gdate.c  |  4 +++-
 glib/gtimer.c | 10 ++++++----
 2 files changed, 9 insertions(+), 5 deletions(-)
---
diff --git a/glib/gdate.c b/glib/gdate.c
index 6e163b8a7..13a87099a 100644
--- a/glib/gdate.c
+++ b/glib/gdate.c
@@ -120,7 +120,9 @@
  *
  * GLib is attempting to unify around the use of 64bit integers to
  * represent microsecond-precision time. As such, this type will be
- * removed from a future version of GLib.
+ * removed from a future version of GLib. A consequence of using `glong` for
+ * `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038
+ * problem.
  */
 
 /**
diff --git a/glib/gtimer.c b/glib/gtimer.c
index 201225523..4f66826ae 100644
--- a/glib/gtimer.c
+++ b/glib/gtimer.c
@@ -538,10 +538,12 @@ g_time_val_from_iso8601 (const gchar *iso_date,
  * variation of ISO 8601 format is required.
  *
  * If @time_ represents a date which is too large to fit into a `struct tm`,
- * %NULL will be returned. This is platform dependent, but it is safe to assume
- * years up to 3000 are supported. The return value of g_time_val_to_iso8601()
- * has been nullable since GLib 2.54; before then, GLib would crash under the
- * same conditions.
+ * %NULL will be returned. This is platform dependent. Note also that since
+ * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it
+ * is subject to the year 2038 problem.
+ *
+ * The return value of g_time_val_to_iso8601() has been nullable since GLib
+ * 2.54; before then, GLib would crash under the same conditions.
  *
  * Returns: (nullable): a newly allocated string containing an ISO 8601 date,
  *    or %NULL if @time_ was too large