[glib/fix-gnulib-msvc-isnan: 1/37] gdatetime: Document that specific AM/PM formatting is discouraged

[Chun-wei Fan <fanchunwei src gnome org>]

commit ff83ab233d3ee7a014fef922ce3b3fb61db791ee
Author: Philip Withnall <withnall endlessm com>
Date:   Thu Apr 9 12:26:12 2020 +0100

    gdatetime: Document that specific AM/PM formatting is discouraged
    
    Many locales have no concept of AM/PM notation, and it’s confusing to
    them. It’s an Anglo-centric concept which doesn’t belong in the API at
    this level — instead, programs should use more generic format specifiers
    which leave the details of how to format a date/time to the locale.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    Fixes: #2082

 glib/gdatetime.c | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
---
diff --git a/glib/gdatetime.c b/glib/gdatetime.c
index 737afdbe0..a72ad8a45 100644
--- a/glib/gdatetime.c
+++ b/glib/gdatetime.c
@@ -3358,10 +3358,14 @@ g_date_time_format_utf8 (GDateTime   *datetime,
  * - \%M: the minute as a decimal number (range 00 to 59)
  * - \%p: either "AM" or "PM" according to the given time value, or the
  *   corresponding  strings for the current locale.  Noon is treated as
- *   "PM" and midnight as "AM".
+ *   "PM" and midnight as "AM". Use of this format specifier is discouraged, as
+ *   many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
  * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
- *   the current locale
- * - \%r: the time in a.m. or p.m. notation
+ *   the current locale. Use of this format specifier is discouraged, as
+ *   many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
+ * - \%r: the time in a.m. or p.m. notation. Use of this format specifier is
+ *   discouraged, as many locales have no concept of AM/PM formatting. Use \%c
+ *   or \%X instead.
  * - \%R: the time in 24-hour notation (\%H:\%M)
  * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
  *   00:00:00 UTC