Tidy up QTimeZone documentation

Update to reflect changes in reality now that I can more faithfully
describe what's happening (thanks to lessons learned during L10n of
display names, though that work isn't in 6.8).

Pick-to: 6.5
Change-Id: I248c924af598c8e8d6cd84675ac04e1733927355
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 1dd785d10d69b0705f86e1580c058d8cd017798b)

src/corelib/time/qtimezone.cpp

@@ -322,10 +322,10 @@ Q_GLOBAL_STATIC(QTimeZoneSingleton, global_tz);
 
     The time zone offset data for a given moment in time.
 
-    This provides the time zone offsets and abbreviation to use at that moment
+    This provides the time zone offsets and abbreviation to use at a given
-    in time. When a function returns this type, it may use an invalid datetime
+    moment in time. When a function returns this type, it may use an invalid
-    to indicate that the query it is answering has no valid answer, so check
+    datetime to indicate that the query it is answering has no valid answer, so
-    \c{atUtc.isValid()} before using the results.
+    check \c{atUtc.isValid()} before using the results.
 
     \list
     \li OffsetData::atUtc  The datetime of the offset data in UTC time.
@@ -514,9 +514,10 @@ QTimeZone::QTimeZone(int offsetSeconds)
     by territory().  The \a comment is an optional note that may be displayed in
     a GUI to assist users in selecting a time zone.
 
-    The \a zoneId \e{must not} be one of the available system IDs returned by
+    The \a offsetSeconds from UTC must be in the range -16 hours to +16 hours.
-    availableTimeZoneIds(). The \a offsetSeconds from UTC must be in the range
+    The \a zoneId \e{must not} be an ID for which isTimeZoneIdAvailable() is
-    -16 hours to +16 hours.
+    true, unless it is a UTC-offset name that doesn't appear in
+    availableTimeZoneIds().
 
     If the custom time zone does not have a specific territory then set it to the
     default value of QLocale::AnyTerritory.
@@ -922,15 +923,15 @@ QString QTimeZone::comment() const
 }
 
 /*!
-    Returns the localized time zone display name at the given \a atDateTime
+    Returns the localized time zone display name.
-    for the given \a nameType in the given \a locale.  The \a nameType and
-    \a locale requested may not be supported on all platforms, in which case
-    the best available option will be returned.
 
-    If the \a locale is not provided then the application default locale will
+    The name returned is the one for the given \a locale, applicable at the
-    be used.
+    given \a atDateTime, and of the form indicated by \a nameType. The display
+    name may change depending on DST or historical events.
 
-    The display name may change depending on DST or historical events.
+    If the \a locale is not provided, then the application default locale will
+    be used. For custom timezones created by client code, the data supplied to
+    the constructor are used, as no localization data will be available for it.
 
     This method is only available when feature \c timezone is enabled.
 
@@ -960,16 +961,16 @@ QString QTimeZone::displayName(const QDateTime &atDateTime, NameType nameType,
 }
 
 /*!
-    Returns the localized time zone display name for the given \a timeType
+    Returns the localized time zone display name.
-    and \a nameType in the given \a locale. The \a nameType and \a locale
-    requested may not be supported on all platforms, in which case the best
-    available option will be returned.
 
-    If the \a locale is not provided then the application default locale will
+    The name returned is the one for the given \a locale, applicable when the
-    be used.
+    given \a timeType is in effect and of the form indicated by \a nameType.
+    Where the time zone display names have changed over time, the current names
+    will be used.
 
-    Where the time zone display names have changed over time then the most
+    If the \a locale is not provided, then the application default locale will
-    recent names will be used.
+    be used. For custom timezones created by client code, the data supplied to
+    the constructor are used, as no localization data will be available for it.
 
     This method is only available when feature \c timezone is enabled.
 
@@ -998,11 +999,14 @@ QString QTimeZone::displayName(TimeType timeType, NameType nameType,
 }
 
 /*!
-    Returns the time zone abbreviation at the given \a atDateTime.  The
+    Returns the time zone abbreviation at the given \a atDateTime.
-    abbreviation may change depending on DST or even historical events.
 
-    Note that the abbreviation is not guaranteed to be unique to this time zone
+    The abbreviation may change depending on DST or even historical events.
-    and should not be used in place of the ID or display name.
+
+    \note The abbreviation is not guaranteed to be unique to this time zone and
+    should not be used in place of the ID or display name. The abbreviation may
+    be localized, depending on the underlying operating system. To get consistent
+    localization, use \c {displayName(atDateTime, QTimeZone::ShortName, locale)}.
 
     This method is only available when feature \c timezone is enabled.
 
@@ -1194,9 +1198,10 @@ bool QTimeZone::isDaylightTime(const QDateTime &atDateTime) const
     Returns the effective offset details at the given \a forDateTime.
 
     This is the equivalent of calling abbreviation() and all three offset
-    functions individually but is more efficient. If this data is not available
+    functions individually but may be more efficient and may get a different
-    for the given datetime, an invalid OffsetData will be returned with an
+    localization for the abbreviation. If this data is not available for the
-    invalid QDateTime as its \c atUtc.
+    given datetime, an invalid OffsetData will be returned with an invalid
+    QDateTime as its \c atUtc.
 
     This method is only available when feature \c timezone is enabled.