QMetaType/QVariant: update docs that canConvert() operates on types

Not on values. That is, it indicates whether there is a conversion path
from origin type to the destination type, not that the conversion will
succeed when attempted. For example:

  QObject *o = new QAbstractItemModel;
  QVariant variant = QVariant::fromValue(o);
  qDebug() << variant.canConvert<QAbstractItemModel*>();

This conversion *will* succeed for this particular value of a QObject*,
so canConvert() must return true for conversions between QObject* and
QAbstractItemModel*, despite not all such conversions being possible.

This is also done in preparation of changes being done to the conversion
routines that may cause some FP->integer conversions to fail depending
on the value of the FP.

Fixes: QTBUG-135619
Task-number: QTBUG-135285
Pick-to: 6.8
Change-Id: I138e34fb61a8b8772c8bfffdf75787a2e007d847
Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
Reviewed-by: Lars Knoll <lars@knoll.priv.no>
(cherry picked from commit 7cf49085eb47ae660d05e8579c08a3ad3be75021)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/kernel/qmetatype.cpp

@@ -2525,7 +2525,14 @@ bool QMetaType::canView(QMetaType fromType, QMetaType toType)
 
 /*!
     Returns \c true if QMetaType::convert can convert from \a fromType to
-    \a toType.
+    \a toType. Note this is mostly about the ability to execute the conversion,
+    while the actual conversion may fail when attempted (for example,
+    converting a floating point value to an integer outside of its range).
+
+    The registerConverter() function can be used to register additional
+    conversions, either between a built-in type and a non-built-in one, or
+    between two non-built-in types. This function will return \c true if the
+    conversion path is registered.
 
     The following conversions are supported by Qt:
 
@@ -2579,11 +2586,18 @@ bool QMetaType::canView(QMetaType fromType, QMetaType toType)
     \row \li \l QMetaType::QUuid \li \l QMetaType::QByteArray, \l QMetaType::QString
     \endtable
 
-    Casting between primitive type (int, float, bool etc.) is supported.
+    Other supported conversions include between all primitive types (\c int, \c
+    float, \c bool, etc., including all enums) and between any pointer type and
+    \c{std::nullptr_t}. Enumerations can also be converted to QString and
+    QByteArray.
 
-    Converting between pointers of types derived from QObject will also return true for this
-    function if a qobject_cast from the type described by \a fromType to the type described
-    by \a toType would succeed.
+    If both \a fromType and \a toType are types deriving from QObject (or
+    pointers to them), this function will also return \c true if one of the
+    types is derived from the other. That is, it returns true if
+    \c{static_cast<>} from the type described by \a fromType to the type
+    described by \a toType would compile. The convert() function operates like
+    qobject_cast() and verifies the dynamic type of the object pointed to by
+    the QVariant.
 
     A cast from a sequential container will also return true for this
     function if the \a toType is QVariantList.

src/corelib/kernel/qvariant.cpp

@@ -2068,6 +2068,10 @@ QVariantList QVariant::toList() const
     type, \a type. Such casting is done automatically when calling the
     toInt(), toBool(), ... methods.
 
+    Note this function operates only on the variant's type, not the contents.
+    It indicates whether there is a conversion path from this variant to \a
+    type, not that the conversion will succeed when attempted.
+
     \sa QMetaType::canConvert()
 */