From 5ff637cc140abc07c4c7934fcd6a048a3d0aa66f Mon Sep 17 00:00:00 2001
From: Thiago Macieira <thiago.macieira@intel.com>
Date: Fri, 26 Aug 2022 11:53:00 -0300
Subject: [PATCH] QMetaType/Doc: update some wording about type registration

Type registration isn't necessary any more, unless you're trying to look
up a name back to ID or QMetaType object. It hasn't been since 6.0.

Drive-by update the example not to use deprecated API.

Drive-by remove the paragraph about requirements that aren't accurate
any more.

Pick-to: 6.4
Task-number: QTBUG-104858
Change-Id: Ic6547f8247454b47baa8fffd170eecb66719fa65
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
---
 .../code/src_corelib_kernel_qmetatype.cpp     | 10 +++----
 src/corelib/kernel/qmetatype.cpp              | 29 +++++++++----------
 2 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp
index b66951357d..a213ccbca6 100644
--- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp
@@ -35,12 +35,12 @@ MyStruct s2 = var.value<MyStruct>();
 
 
 //! [3]
-int id = QMetaType::type("MyClass");
-if (id != QMetaType::UnknownType) {
-    void *myClassPtr = QMetaType::create(id);
+QMetaType type = QMetaType::fromName("MyClass");
+if (type.isValid()) {
+    void *myClassPtr = type.create();
     ...
-    QMetaType::destroy(id, myClassPtr);
-    myClassPtr = 0;
+    type.destroy(myClassPtr);
+    myClassPtr = nullptr;
 }
 //! [3]
 
diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index 3e38f68137..1bacf6c940 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -417,7 +417,8 @@ const char *QtMetaTypePrivate::typedefNameForType(const QtPrivate::QMetaTypeInte
     \omitvalue LastCoreType
     \omitvalue LastGuiType
 
-    Additional types can be registered using Q_DECLARE_METATYPE().
+    Additional types can be registered using qRegisterMetaType() or by calling
+    registerType().
 
     \sa type(), typeName()
 */
@@ -465,17 +466,19 @@ const char *QtMetaTypePrivate::typedefNameForType(const QtPrivate::QMetaTypeInte
     The class is used as a helper to marshall types in QVariant and
     in queued signals and slots connections. It associates a type
     name to a type so that it can be created and destructed
-    dynamically at run-time. Declare new types with Q_DECLARE_METATYPE()
-    to make them available to QVariant and other template-based functions.
-    Call qRegisterMetaType() to make types available to non-template based
-    functions, such as the queued signal and slot connections.
+    dynamically at run-time.
 
-    Any class or struct that has a public default
-    constructor, a public copy constructor, and a public destructor
-    can be registered.
+    Type names can be registered with QMetaType by using either
+    qRegisterMetaType() or registerType(). Registration is not required for
+    most operations; it's only required for operations that attempt to resolve
+    a type name in string form back to a QMetaType object or the type's ID.
+    Those include some old-style signal-slot connections using
+    QObject::connect(), reading user-types from \l QDataStream to \l QVariant,
+    or binding to other languages and IPC mechanisms, like QML, D-Bus,
+    JavaScript, etc.
 
-    The following code allocates and destructs an instance of
-    \c{MyClass}:
+    The following code allocates and destructs an instance of \c{MyClass} by
+    its name, which requires that \c{MyClass} have been previously registered:
 
     \snippet code/src_corelib_kernel_qmetatype.cpp 3
 
@@ -2775,9 +2778,6 @@ Q_CORE_EXPORT int qMetaTypeTypeInternal(const char *typeName)
     Returns \c true if the object is saved successfully; otherwise
     returns \c false.
 
-    The type must have been registered with Q_DECLARE_METATYPE()
-    beforehand.
-
     Normally, you should not need to call this function directly.
     Instead, use QVariant's \c operator<<(), which relies on save()
     to stream custom types.
@@ -2816,9 +2816,6 @@ bool QMetaType::save(QDataStream &stream, const void *data) const
     Returns \c true if the object is loaded successfully; otherwise
     returns \c false.
 
-    The type must have been registered with Q_DECLARE_METATYPE()
-    beforehand.
-
     Normally, you should not need to call this function directly.
     Instead, use QVariant's \c operator>>(), which relies on load()
     to stream custom types.