Correct documentation of QDateTime's comparisons

These previously claimed that date-times with different date, time or
zone are different; as pointed out by Marcus Tillmanns, this is not
true. Corrected the documentation to talk about representing the same
moment in time.

In the process, renamed the snippet shared with several other docs,
since the snippet name only focused on the other part of what it was
saying.

Pick-to: 6.6 6.5 6.2 5.15
Fixes: QTBUG-122973
Change-Id: Ifd74da84aad0b0dca688c131b6ae6a7b65633225
Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit cb5aac06cf7b3982a42004fd7455d78a3caba550)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/time/qdatetime.cpp

@@ -5201,13 +5201,20 @@ bool QDateTime::equals(const QDateTime &other) const
 /*!
     \fn bool QDateTime::operator==(const QDateTime &lhs, const QDateTime &rhs)
 
-    Returns \c true if \a lhs is the same as \a rhs; otherwise returns \c false.
+    Returns \c true if \a lhs represents the same moment in time as \a rhs;
+    otherwise returns \c false.
 
-//! [invalid-vs-valid-datetime]
+//! [datetime-order-details]
-    Two datetimes are different if either the date, the time, or the time zone
+    Two datetimes using different time representations can have different
-    components are different. Since 5.14, all invalid datetimes are equal (and
+    offsets from UTC. In this case, they may compare equivalent even if their \l
-    less than all valid datetimes).
+    date() and \l time() differ, if that difference matches the difference in
-//! [invalid-vs-valid-datetime]
+    UTC offset. If their \c date() and \c time() coincide, the one with higher
+    offset from UTC is less (earlier) than the one with lower offset. As a
+    result, datetimes are only weakly ordered.
+
+    Since 5.14, all invalid datetimes are equivalent and less than all valid
+    datetimes.
+//! [datetime-order-details]
 
     \sa operator!=(), operator<(), operator<=(), operator>(), operator>=()
 */
@@ -5218,7 +5225,7 @@ bool QDateTime::equals(const QDateTime &other) const
     Returns \c true if \a lhs is different from \a rhs; otherwise returns \c
     false.
 
-    \include qdatetime.cpp invalid-vs-valid-datetime
+    \include qdatetime.cpp datetime-order-details
 
     \sa operator==()
 */
@@ -5244,7 +5251,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs)
     Returns \c true if \a lhs is earlier than \a rhs;
     otherwise returns \c false.
 
-    \include qdatetime.cpp invalid-vs-valid-datetime
+    \include qdatetime.cpp datetime-order-details
 
     \sa operator==()
 */
@@ -5255,7 +5262,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs)
     Returns \c true if \a lhs is earlier than or equal to \a rhs; otherwise
     returns \c false.
 
-    \include qdatetime.cpp invalid-vs-valid-datetime
+    \include qdatetime.cpp datetime-order-details
 
     \sa operator==()
 */
@@ -5265,7 +5272,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs)
 
     Returns \c true if \a lhs is later than \a rhs; otherwise returns \c false.
 
-    \include qdatetime.cpp invalid-vs-valid-datetime
+    \include qdatetime.cpp datetime-order-details
 
     \sa operator==()
 */
@@ -5276,7 +5283,7 @@ Qt::weak_ordering compareThreeWay(const QDateTime &lhs, const QDateTime &rhs)
     Returns \c true if \a lhs is later than or equal to \a rhs;
     otherwise returns \c false.
 
-    \include qdatetime.cpp invalid-vs-valid-datetime
+    \include qdatetime.cpp datetime-order-details
 
     \sa operator==()
 */