Doc: improve documentation about QVariant to JSON lossy conversions

Fixes: QTBUG-85299
Pick-to: 5.15
Change-Id: I24006db8360041f598c5fffd161c77638a54a27e
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

2 files changed, 43 insertions, 12 deletions

diff --git a/src/corelib/serialization/qjsoncbor.cpp b/src/corelib/serialization/qjsoncbor.cpp
index 8bb04fa3bf..e0eab74a02 100644
--- a/src/corelib/serialization/qjsoncbor.cpp
+++ b/src/corelib/serialization/qjsoncbor.cpp
@@ -679,17 +679,22 @@ static void appendVariant(QCborContainerPrivate *d, const QVariant &variant)
       \row  \li \l QUuid                    \li Uuid
     \endtable
 
-    For any other types, this function will return Null if the QVariant itself
-    is null, and otherwise will try to convert to string using
-    QVariant::toString(). If the conversion to string fails, this function
-    returns Undefined.
+    If QVariant::isNull() returns true, a null QCborValue is returned or
+    inserted into the list or object, regardless of the type carried by
+    QVariant. Note the behavior change in Qt 6.0 affecting QVariant::isNull()
+    also affects this function.
+
+    For other types not listed above, a conversion to string will be attempted,
+    usually but not always by calling QVariant::toString(). If the conversion
+    fails the value is replaced by an Undefined CBOR value. Note that
+    QVariant::toString() is also lossy for the majority of types.
 
     Please note that the conversions via QVariant::toString() are subject to
-    change at any time. QCborValue may be extended in the future to support
-    more types, which will result in a change in how this function performs
-    conversions.
+    change at any time. Both QVariant and QCborValue may be extended in the
+    future to support more types, which will result in a change in how this
+    function performs conversions.
 
-    \sa toVariant(), fromJsonValue(), QCborArray::toVariantList(), QCborMap::toVariantMap()
+    \sa toVariant(), fromJsonValue(), QCborArray::toVariantList(), QCborMap::toVariantMap(), QJsonValue::fromVariant()
  */
 QCborValue QCborValue::fromVariant(const QVariant &variant)
 {
diff --git a/src/corelib/serialization/qjsonvalue.cpp b/src/corelib/serialization/qjsonvalue.cpp
index 5eb33bd2a3..34fa84cdc1 100644
--- a/src/corelib/serialization/qjsonvalue.cpp
+++ b/src/corelib/serialization/qjsonvalue.cpp
@@ -439,10 +439,36 @@ void QJsonValue::swap(QJsonValue &other) noexcept
             "stringification" of map keys.
     \endtable
 
-    For all other QVariant types a conversion to a QString will be attempted. If the returned string
-    is empty, a Null QJsonValue will be stored, otherwise a String value using the returned QString.
-
-    \sa toVariant()
+    \section2 Loss of information and other types
+
+    QVariant can carry more information than is representable in JSON. If the
+    QVariant is not one of the types above, the conversion is not guaranteed
+    and is subject to change in future versions of Qt, as the UUID one did.
+    Code should strive not to use any other types than those listed above.
+
+    If QVariant::isNull() returns true, a null QJsonValue is returned or
+    inserted into the list or object, regardless of the type carried by
+    QVariant. Note the behavior change in Qt 6.0 affecting QVariant::isNull()
+    also affects this function.
+
+    A floating point value that is either an infinity or NaN will be converted
+    to a null JSON value. Since Qt 6.0, QJsonValue can store the full precision
+    of any 64-bit signed integer without loss, but in previous versions values
+    outside the range of ±2^53 may lose precision. Unsigned 64-bit values
+    greater than or equal to 2^63 will either lose precision or alias to
+    negative values, so QMetaType::ULongLong should be avoided.
+
+    For other types not listed above, a conversion to string will be attempted,
+    usually but not always by calling QVariant::toString(). If the conversion
+    fails the value is replaced by a null JSON value. Note that
+    QVariant::toString() is also lossy for the majority of types.
+
+    Please note that the conversions via QVariant::toString() are subject to
+    change at any time. Both QVariant and QJsonValue may be extended in the
+    future to support more types, which will result in a change in how this
+    function performs conversions.
+
+    \sa toVariant(), QCborValue::fromVariant()
  */
 QJsonValue QJsonValue::fromVariant(const QVariant &variant)
 {