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>

1 files changed, 20 insertions, 9 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