From a95d81e786ea839e59d6d6594c7d648b78a3c226 Mon Sep 17 00:00:00 2001
From: Edward Welbourne <edward.welbourne@qt.io>
Date: Thu, 8 Sep 2016 18:57:46 +0200
Subject: Q(Date|Time)+::(to|from)String(): mention relevant QLocale methods

The const QString &format variants of these methods lack adequate
control over the locale used; the Qt::DateFormat variants give only
limited control over the format string.  So reference the QLocale
methods that provide the general case, in the docs of each.  Also made
the \sa cross-referencing among these methods a little more coherent.

Task-number: QTBUG-55632
Change-Id: Icd0c8548045e74879e941ba089c3bdea78f14e34
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
---
 src/corelib/tools/qdatetime.cpp | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

(limited to 'src/corelib')

diff --git a/src/corelib/tools/qdatetime.cpp b/src/corelib/tools/qdatetime.cpp
index e6d0b97836..6b09b4107c 100644
--- a/src/corelib/tools/qdatetime.cpp
+++ b/src/corelib/tools/qdatetime.cpp
@@ -842,7 +842,7 @@ static QString toStringIsoDate(qint64 jd)
     range 0 to 9999. This restriction may apply to locale-aware
     formats as well, depending on the locale settings.
 
-    \sa shortDayName(), shortMonthName()
+    \sa fromString(), shortDayName(), shortMonthName(), QLocale::toString()
 */
 QString QDate::toString(Qt::DateFormat format) const
 {
@@ -918,7 +918,7 @@ QString QDate::toString(Qt::DateFormat format) const
 
     If the datetime is invalid, an empty string will be returned.
 
-    \sa QDateTime::toString(), QTime::toString(), QLocale::toString()
+    \sa fromString(), QDateTime::toString(), QTime::toString(), QLocale::toString()
 
 */
 QString QDate::toString(const QString& format) const
@@ -1185,6 +1185,8 @@ qint64 QDate::daysTo(const QDate &d) const
     Note for Qt::TextDate: It is recommended that you use the
     English short month names (e.g. "Jan"). Although localized month
     names can also be used, they depend on the user's locale settings.
+
+    \sa toString(), QLocale::toDate()
 */
 QDate QDate::fromString(const QString& string, Qt::DateFormat format)
 {
@@ -1303,8 +1305,8 @@ QDate QDate::fromString(const QString& string, Qt::DateFormat format)
 
     \snippet code/src_corelib_tools_qdatetime.cpp 3
 
-    \sa QDateTime::fromString(), QTime::fromString(), QDate::toString(),
-        QDateTime::toString(), QTime::toString()
+    \sa toString(), QDateTime::fromString(), QTime::fromString(),
+        QLocale::toDate()
 */
 
 QDate QDate::fromString(const QString &string, const QString &format)
@@ -1571,7 +1573,7 @@ int QTime::msec() const
 
     If the time is invalid, an empty string will be returned.
 
-    \sa QDate::toString(), QDateTime::toString()
+    \sa fromString(), QDate::toString(), QDateTime::toString(), QLocale::toString()
 */
 
 QString QTime::toString(Qt::DateFormat format) const
@@ -1644,7 +1646,7 @@ QString QTime::toString(Qt::DateFormat format) const
     If the time is invalid, an empty string will be returned.
     If \a format is empty, the default format "hh:mm:ss" is used.
 
-    \sa QDate::toString(), QDateTime::toString(), QLocale::toString()
+    \sa fromString(), QDate::toString(), QDateTime::toString(), QLocale::toString()
 */
 QString QTime::toString(const QString& format) const
 {
@@ -1929,6 +1931,8 @@ static QTime fromIsoTimeString(const QStringRef &string, Qt::DateFormat format,
     this may result in two conversion attempts (if the conversion
     fails for the default locale). This should be considered an
     implementation detail.
+
+    \sa toString(), QLocale::toTime()
 */
 QTime QTime::fromString(const QString& string, Qt::DateFormat format)
 {
@@ -2002,8 +2006,8 @@ QTime QTime::fromString(const QString& string, Qt::DateFormat format)
 
     \snippet code/src_corelib_tools_qdatetime.cpp 8
 
-    \sa QDateTime::fromString(), QDate::fromString(), QDate::toString(),
-    QDateTime::toString(), QTime::toString()
+    \sa toString(), QDateTime::fromString(), QDate::fromString(),
+    QLocale::toTime()
 */
 
 QTime QTime::fromString(const QString &string, const QString &format)
@@ -3520,7 +3524,8 @@ void QDateTime::setTime_t(uint secsSince1Jan1970UTC)
     range 0 to 9999. This restriction may apply to locale-aware
     formats as well, depending on the locale settings.
 
-    \sa QDate::toString(), QTime::toString(), Qt::DateFormat
+    \sa fromString(), QDate::toString(), QTime::toString(),
+    QLocale::toString()
 */
 
 QString QDateTime::toString(Qt::DateFormat format) const
@@ -3660,7 +3665,7 @@ QString QDateTime::toString(Qt::DateFormat format) const
 
     If the datetime is invalid, an empty string will be returned.
 
-    \sa QDate::toString(), QTime::toString(), QLocale::toString()
+    \sa fromString(), QDate::toString(), QTime::toString(), QLocale::toString()
 */
 QString QDateTime::toString(const QString& format) const
 {
@@ -4356,6 +4361,8 @@ int QDateTime::utcOffset() const
     Note for Qt::TextDate: It is recommended that you use the
     English short month names (e.g. "Jan"). Although localized month
     names can also be used, they depend on the user's locale settings.
+
+    \sa toString(), QLocale::toDateTime()
 */
 QDateTime QDateTime::fromString(const QString& string, Qt::DateFormat format)
 {
@@ -4657,8 +4664,8 @@ QDateTime QDateTime::fromString(const QString& string, Qt::DateFormat format)
 
     \snippet code/src_corelib_tools_qdatetime.cpp 14
 
-    \sa QDate::fromString(), QTime::fromString(), QDate::toString(),
-    QDateTime::toString(), QTime::toString()
+    \sa toString(), QDate::fromString(), QTime::fromString(),
+    QLocale::toDateTime()
 */
 
 QDateTime QDateTime::fromString(const QString &string, const QString &format)
-- 
cgit v1.2.3