Doc: Specify that class name must be fully qualified

To avoid confusion, all macros that take a class name as an argument should specify that the class name needs to be fully qualified, even
if you're already inside the namespace.

Fixes: QTBUG-110718
Change-Id: Icaed4be5df44e8d35ef382a918246ed03b0bb0c5
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
(cherry picked from commit 4f465236f2259680117ee97d2310d79de1a14293)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 25 insertions, 3 deletions

diff --git a/src/qml/doc/src/includes/qualified-class-name.qdocinc b/src/qml/doc/src/includes/qualified-class-name.qdocinc
new file mode 100644
index 0000000000..fce8b45cc0
--- /dev/null
+++ b/src/qml/doc/src/includes/qualified-class-name.qdocinc
@@ -0,0 +1,7 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [class name must be qualified]
+\note The class name needs to be fully qualified, even if you're already
+  inside the namespace.
+//! [class name must be qualified]
diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc
index b456700f89..84fabe9c6f 100644
--- a/src/qml/doc/src/qmlfunctions.qdoc
+++ b/src/qml/doc/src/qmlfunctions.qdoc
@@ -57,6 +57,8 @@
   \l QML_ELEMENT on both of them will cause a conflict.
   Make sure to use \l QML_NAMED_ELEMENT() for one of them instead.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(),
       Q_REVISION(), QML_ADDED_IN_MINOR_VERSION()
 */
@@ -136,8 +138,8 @@
 
   This macro tells Qt which QML \a interfaces the class implements.
   This macro should only be used for interfacing with classes using \l QML_INTERFACE, use \l Q_INTERFACES otherwise.
-  It's required in order for declarative registration via \l QML_ELEMENT to function properly.
-
+  It's required in order for declarative registration via \l QML_ELEMENT to
+  function properly.
 
   \sa QML_INTERFACE, Q_INTERFACES
 */
@@ -155,7 +157,8 @@
   \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or
   \l QML_NAMED_ELEMENT().
 
-  Since Qt 6.0 you can use "" instead of a reason to use a standard message instead.
+  Since Qt 6.0 you can use "" instead of a reason to use a standard message
+  instead.
 
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS
 */
@@ -377,6 +380,8 @@
   {attached property} to other types. This takes effect if the type
   is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(),
       {Providing Attached Properties}
 */
@@ -392,6 +397,8 @@
 
   \warning Members of \a EXTENDED_TYPE are implicitly treated as FINAL.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(),
       {Registering Extension Objects}
 */
@@ -435,6 +442,8 @@
   \note \a EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which
   contains the Q_NAMESPACE macro or a QObject/QGadget.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(),
       {Registering Extension Objects}, Q_ENUM, Q_ENUM_NS
 */
@@ -460,6 +469,8 @@
   the element will be named like the struct it is contained in, not the foreign type.
   See the \l {Extension Objects} for an example.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN_NAMESPACE()
 */
 
@@ -528,6 +539,8 @@
   \l QML_UNAVAILABLE still results in a more specific error message than the usual
   "is not a type" for completely unknown types.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN()
 */
 
@@ -588,6 +601,8 @@
   sequential containers are available under the familiar \e{list<...>} names,
   for example \e{list<QtObject>} or \e{list<font>}.
 
+  \include {qualified-class-name.qdocinc} {class name must be qualified}
+
   \sa QML_ANONYMOUS, QML_FOREIGN()
 */