Clean up docs of QCalendar-related QLocale::toString() variants

Some of the new functions were added without documentation, or without
updating the docs to mention the optional calendars. Shuffle the
methods so that the one with calendar is what the primary
documentation comment describes and the one without is documented as
an overload.

Pick-to: 5.15
Change-Id: Iee4cdb1d3b0ed21a50e205a5275a0695a2667550
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

1 files changed, 59 insertions, 42 deletions

diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index 7692ea3b26..a3429ec9f8 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/src/corelib/text/qlocale.cpp
@@ -1840,27 +1840,62 @@ QString QLocale::toString(QTime time, const QString &format) const
 #endif
 
 /*!
-    \since 5.10
+    \since 5.14
 
     Returns a localized string representation of the given \a date in the
-    specified \a format.
+    specified \a format, optionally for a specified calendar \a cal.
     If \a format is an empty string, an empty string is returned.
 
     \sa QDate::toString()
 */
+QString QLocale::toString(QDate date, QStringView format, QCalendar cal) const
+{
+    return cal.dateTimeToString(format, QDateTime(), date, QTime(), *this);
+}
+
+/*!
+    \since 5.10
+    \overload
+*/
 QString QLocale::toString(QDate date, QStringView format) const
 {
     return QCalendar().dateTimeToString(format, QDateTime(), date, QTime(), *this);
 }
 
 /*!
+    \since 5.14
+
     Returns a localized string representation of the given \a date according
-    to the specified \a format (see dateFormat()).
+    to the specified \a format (see dateFormat()), optionally for a specified
+    calendar \a cal.
 
     \note Some locales may use formats that limit the range of years they can
     represent.
 */
+QString QLocale::toString(QDate date, FormatType format, QCalendar cal) const
+{
+    if (!date.isValid())
+        return QString();
+
+#ifndef QT_NO_SYSTEMLOCALE
+    if (cal.isGregorian() && d->m_data == &globalLocaleData) {
+        QVariant res = systemLocale()->query(format == LongFormat
+                                             ? QSystemLocale::DateToStringLong
+                                             : QSystemLocale::DateToStringShort,
+                                             date);
+        if (!res.isNull())
+            return res.toString();
+    }
+#endif
 
+    QString format_str = dateFormat(format);
+    return toString(date, format_str, cal);
+}
+
+/*!
+    \since 4.5
+    \overload
+*/
 QString QLocale::toString(QDate date, FormatType format) const
 {
     if (!date.isValid())
@@ -1899,7 +1934,7 @@ static bool timeFormatContainsAP(QStringView format)
 }
 
 /*!
-    \since 5.10
+    \since 4.5
 
     Returns a localized string representation of the given \a time according
     to the specified \a format.
@@ -1913,46 +1948,39 @@ QString QLocale::toString(QTime time, QStringView format) const
 }
 
 /*!
-    \since 5.10
+    \since 5.14
 
     Returns a localized string representation of the given \a dateTime according
-    to the specified \a format.
+    to the specified \a format, optionally for a specified calendar \a cal.
     If \a format is an empty string, an empty string is returned.
 
     \sa QDateTime::toString(), QDate::toString(), QTime::toString()
 */
-QString QLocale::toString(const QDateTime &dateTime, QStringView format) const
+QString QLocale::toString(const QDateTime &dateTime, QStringView format, QCalendar cal) const
 {
-    return QCalendar().dateTimeToString(format, dateTime, QDate(), QTime(), *this);
+    return cal.dateTimeToString(format, dateTime, QDate(), QTime(), *this);
 }
 
-QString QLocale::toString(QDate date, QStringView format, QCalendar cal) const
+/*!
+    \since 5.10
+    \overload
+*/
+QString QLocale::toString(const QDateTime &dateTime, QStringView format) const
 {
-    return cal.dateTimeToString(format, QDateTime(), date, QTime(), *this);
+    return QCalendar().dateTimeToString(format, dateTime, QDate(), QTime(), *this);
 }
 
-QString QLocale::toString(QDate date, QLocale::FormatType format, QCalendar cal) const
-{
-    if (!date.isValid())
-        return QString();
-
-#ifndef QT_NO_SYSTEMLOCALE
-    if (cal.isGregorian() && d->m_data == &globalLocaleData) {
-        QVariant res = systemLocale()->query(format == LongFormat
-                                             ? QSystemLocale::DateToStringLong
-                                             : QSystemLocale::DateToStringShort,
-                                             date);
-        if (!res.isNull())
-            return res.toString();
-    }
-#endif
+/*!
+    \since 5.14
 
-    QString format_str = dateFormat(format);
-    return toString(date, format_str, cal);
-}
+    Returns a localized string representation of the given \a dateTime according
+    to the specified \a format (see dateTimeFormat()), optionally for a
+    specified calendar \a cal.
 
-QString QLocale::toString(const QDateTime &dateTime, QLocale::FormatType format,
-                          QCalendar cal) const
+    \note Some locales may use formats that limit the range of years they can
+    represent.
+*/
+QString QLocale::toString(const QDateTime &dateTime, FormatType format, QCalendar cal) const
 {
     if (!dateTime.isValid())
         return QString();
@@ -1972,21 +2000,10 @@ QString QLocale::toString(const QDateTime &dateTime, QLocale::FormatType format,
     return toString(dateTime, format_str, cal);
 }
 
-QString QLocale::toString(const QDateTime &dateTime, QStringView format, QCalendar cal) const
-{
-    return cal.dateTimeToString(format, dateTime, QDate(), QTime(), *this);
-}
-
 /*!
     \since 4.4
-
-    Returns a localized string representation of the given \a dateTime according
-    to the specified \a format (see dateTimeFormat()).
-
-    \note Some locales may use formats that limit the range of years they can
-    represent.
+    \overload
 */
-
 QString QLocale::toString(const QDateTime &dateTime, FormatType format) const
 {
     if (!dateTime.isValid())