Doc: Improve documentation for QLocale::FormatType

LongFormat and ShortFormat are not limited to day and month names.
Different locales might also use numbers for months instead of strings,
so the example is a bit misleading.

Instead of extending the enum description even more there's now
examples in the dateFormat(), timeFormat(), dateTimeFormat()
functions.

Task-number: QTBUG-83841
Pick-to: 5.15
Change-Id: Icea2cbce7e9505d706a2171e7d1f4486abdb20be
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

src/corelib/text/qlocale.cpp

@@ -2081,7 +2081,7 @@ QString QLocale::toString(QDate date, QStringView format) const
 
 /*!
     Returns a localized string representation of the given \a date according
-    to the specified \a format.
+    to the specified \a format (see dateFormat()).
 
     \note Some locales may use formats that limit the range of years they can
     represent.
@@ -2238,7 +2238,7 @@ QString QLocale::toString(const QDateTime &dateTime, QStringView format, QCalend
     \since 4.4
 
     Returns a localized string representation of the given \a dateTime according
-    to the specified \a format.
+    to the specified \a format (see dateTimeFormat()).
 
     \note Some locales may use formats that limit the range of years they can
     represent.
@@ -2267,7 +2267,7 @@ QString QLocale::toString(const QDateTime &dateTime, FormatType format) const
 
 /*!
     Returns a localized string representation of the given \a time in the
-    specified \a format.
+    specified \a format (see timeFormat()).
 */
 
 QString QLocale::toString(QTime time, FormatType format) const
@@ -2295,8 +2295,9 @@ QString QLocale::toString(QTime time, FormatType format) const
 
     Returns the date format used for the current locale.
 
-    If \a format is LongFormat the format will be a long version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
-    Otherwise it uses a shorter version.
+    For example, LongFormat for the \c{en_US} locale is \c{dddd, MMMM d, yyyy},
+    ShortFormat is \c{M/d/yy}.
 
     \sa QDate::toString(), QDate::fromString()
 */
@@ -2325,8 +2326,9 @@ QString QLocale::dateFormat(FormatType format) const
 
     Returns the time format used for the current locale.
 
-    If \a format is LongFormat the format will be a long version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
-    Otherwise it uses a shorter version.
+    For example, LongFormat for the \c{en_US} locale is \c{h:mm:ss AP t},
+    ShortFormat is \c{h:mm AP}.
 
     \sa QTime::toString(), QTime::fromString()
 */
@@ -2355,8 +2357,9 @@ QString QLocale::timeFormat(FormatType format) const
 
     Returns the date time format used for the current locale.
 
-    If \a format is ShortFormat the format will be a short version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
-    Otherwise it uses a longer version.
+    For example, LongFormat for the \c{en_US} locale is \c{dddd, MMMM d, yyyy h:mm:ss AP t},
+    ShortFormat is \c{M/d/yy h:mm AP}.
 
     \sa QDateTime::toString(), QDateTime::fromString()
 */
@@ -2841,6 +2844,10 @@ QList<QLocale::Country> QLocale::countriesForLanguage(Language language)
     Returns the localized name of \a month, in the format specified
     by \a type.
 
+    For example, if the locale is \c en_US and \a month is 1,
+    \l LongFormat will return \c January. \l ShortFormat \c Jan,
+    and \l NarrowFormat \c J.
+
     \sa dayName(), standaloneMonthName()
 */
 QString QLocale::monthName(int month, FormatType type) const
@@ -2871,6 +2878,10 @@ QString QLocale::standaloneMonthName(int month, FormatType type) const
     Monday, 2 represents Tuesday and so on), in the format specified
     by \a type.
 
+    For example, if the locale is \c en_US and \a day is 1,
+    \l LongFormat will return \c Monday, \l ShortFormat \c Mon,
+    and \l NarrowFormat \c M.
+
     \sa monthName(), standaloneDayName()
 */
 QString QLocale::dayName(int day, FormatType type) const

src/corelib/text/qlocale.qdoc

@@ -936,24 +936,25 @@
 /*!
     \enum QLocale::FormatType
 
-    This enum describes the types of format that can be used when
+    This enum describes the different formats that can be used when
-    converting QDate and QTime objects to strings.
+    converting QDate, QTime, and QDateTime objects, as well
+    as months and days, to strings specific to the locale.
 
-    \value LongFormat The long version of day and month names; for
+    \value LongFormat Longer format.
-    example, returning "January" as a month name.
 
-    \value ShortFormat The short version of day and month names; for
+    \value ShortFormat Shorter format.
-    example, returning "Jan" as a month name.
 
-    \value NarrowFormat A special version of day and month names for
+    \value NarrowFormat A special version for use when space is very limited.
-    use when space is limited; for example, returning "J" as a month
+
-    name. Note that the narrow format might contain the same text for
+    \note \c NarrowFormat might contain the same text for
-    different months and days or it can even be an empty string if the
+    different months and days. It can even be an empty string if the
     locale doesn't support narrow names, so you should avoid using it
     for date formatting. Also, for the system locale this format is
-    the same as ShortFormat.
+    the same as \c ShortFormat.
 
-    \sa QDateTime::toString(), QDate::toString(), QTime::toString()
+    \sa dateFormat(), timeFormat(), dateTimeFormat()
+    \sa monthName(), standaloneMonthName(), dayName(), standaloneDayName()
+    \sa toDate(), toTime(), toDateTime()
 */
 
 /*!