Document potential problems with empty timezone names

Make clear that QTimeZone::displayName() may return an empty string
and that Q(Date)?Time::toString() may consequently skip a zone text.

In the process, fix a typo in the QTime::toString() docs and add the
zone-naming formats to the mention of when applying
QLocale::toString() to the Q(Date)?Time may be preferred, moving the
earlier discussion of AM/PM that it joins to sit just after the table.

Pick-to: 6.5
Change-Id: I313b8b1b452078421252a05aa599bc5f91d43105
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 5d18017213c110d5a99abeaf53cc4d29a6bfb660)
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

src/corelib/time/qdatetime.cpp

@@ -2152,8 +2152,10 @@ QString QTime::toString(Qt::DateFormat format) const
     \fn QString QTime::toString(const QString &format) const
     \fn QString QTime::toString(QStringView format) const
 
-    Returns the time as a string. The \a format parameter determines
+    Returns a string representing the time.
-    the format of the result string.
+
+    The \a format parameter determines the format of the result string. If the
+    time is invalid, an empty string will be returned.
 
     These expressions may be used:
 
@@ -2198,7 +2200,7 @@ QString QTime::toString(Qt::DateFormat format) const
              change of case.
     \row \li t
          \li The timezone abbreviation (for example "CEST"). Note that time zone
-             abbreviations are not unique. In particular, \l toString() cannot
+             abbreviations are not unique. In particular, \l fromString() cannot
              parse this.
     \row \li tt
          \li The timezone's offset from UTC with no colon between the hours and
@@ -2216,6 +2218,14 @@ QString QTime::toString(Qt::DateFormat format) const
              in use.
     \endtable
 
+    \note To get localized forms of AM or PM (the \c{AP}, \c{ap}, \c{A}, \c{a},
+    \c{aP} or \c{Ap} formats) or of time zone representations (the \c{t}
+    formats), use QLocale::system().toString().
+
+    When the timezone cannot be determined or no suitable representation of it
+    is available, the \c{t} forms to represent it may be skipped. See \l
+    QTimeZone::displayName() for details of when it returns an empty string.
+
     Any non-empty sequence of characters enclosed in single quotes will be
     included verbatim in the output string (stripped of the quotes), even if it
     contains formatting characters. Two consecutive single quotes ("''") are
@@ -2236,11 +2246,6 @@ QString QTime::toString(Qt::DateFormat format) const
     \row \li H:m:s a      \li 14:13:9 pm
     \endtable
 
-    If the time is invalid, an empty string will be returned.
-
-    \note To get localized forms of AM or PM (the AP, ap, A, a, aP or Ap
-    formats), use QLocale::system().toString().
-
     \note If a format character is repeated more times than the longest
     expression in the table above using it, this part of the format will be read
     as several expressions with no separator between them; the longest above,

src/corelib/time/qtimezone.cpp

@@ -928,12 +928,19 @@ QString QTimeZone::comment() const
     The name returned is the one for the given \a locale, applicable at the
     given \a atDateTime, and of the form indicated by \a nameType. The display
     name may change depending on DST or historical events.
+//! [display-name-caveats]
+    If no suitably localized name of the given type is available, another name
+    type may be used, or an empty string may be returned.
 
     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.
+    If this timezone is invalid, an empty string is returned. This may also
+    arise for the representation of local time if determining the system time
+    zone fails.
 
     This method is only available when feature \c timezone is enabled.
+//! [display-name-caveats]
 
     \sa abbreviation()
 */
@@ -967,12 +974,7 @@ QString QTimeZone::displayName(const QDateTime &atDateTime, NameType nameType,
     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.
-
+    \include qtimezone.cpp display-name-caveats
-    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.
 
     \sa abbreviation()
 */