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>

2 files changed, 33 insertions, 21 deletions

diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index e31b5c9155..96b6646c90 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/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.
-    Otherwise it uses a shorter version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
+    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.
-    Otherwise it uses a shorter version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
+    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.
-    Otherwise it uses a longer version.
+    If \a format is LongFormat, the format will be elaborate, otherwise it will be short.
+    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
diff --git a/src/corelib/text/qlocale.qdoc b/src/corelib/text/qlocale.qdoc
index e470a317f2..eb497d9386 100644
--- a/src/corelib/text/qlocale.qdoc
+++ b/src/corelib/text/qlocale.qdoc
@@ -936,24 +936,25 @@
 /*!
     \enum QLocale::FormatType
 
-    This enum describes the types of format that can be used when
-    converting QDate and QTime objects to strings.
+    This enum describes the different formats that can be used when
+    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
-    example, returning "January" as a month name.
+    \value LongFormat Longer format.
 
-    \value ShortFormat The short version of day and month names; for
-    example, returning "Jan" as a month name.
+    \value ShortFormat Shorter format.
 
-    \value NarrowFormat A special version of day and month names for
-    use when space is limited; for example, returning "J" as a month
-    name. Note that the narrow format might contain the same text for
-    different months and days or it can even be an empty string if the
+    \value NarrowFormat A special version for use when space is very limited.
+
+    \note \c NarrowFormat might contain the same text for
+    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()
 */
 
 /*!