diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index 66dec2979c4..ccf863b566e 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -220,6 +220,16 @@ const char *QtMetaTypePrivate::typedefNameForType(const QtPrivate::QMetaTypeInte
     to be registered with QMetaType using either Q_DECLARE_METATYPE()
     or qRegisterMetaType().
 
+    Do not use this macro to avoid complaints or errors from \l moc about
+    incomplete property types when the pointee type is used as a complete type in
+    other contexts in the program. Use \l{Q_MOC_INCLUDE} instead when
+    the full definition of the type is available, but you prefer a forward
+    declaration in the header to reduce compilation times.
+
+    \warning Don't use Q_DECLARE_OPAQUE_POINTER with pointers to a Q_OBJECT or
+    a gadget class, as that risks introducing inconsistent information in the
+    meta-type system.
+
     \sa Q_DECLARE_METATYPE(), qRegisterMetaType()
 */