qdoc: Support auto-generated values in QML docs from C++ enums

C++ classes registered to QML expose also enums to QML, with values
available under <RegisteredQmlName>.<value>.

Add a new meta-command, \qmlenumeratorsfrom, to use in \qmlproperty
documentation. This command is used for associating a documented
C++ enum with a QML property.

The command takes a fully qualified C++ enum as an argument.

When set, the enum values and their descriptions are retrieved from
C++ \enum documentation during generation of the QML property.

Instead of the '<namespace>::' prefix that's used in C++ enum
documentation, use '<RegisteredQmlName>.' as the prefix. By default,
the prefix is the parent QML type name, but a custom prefix can
be provided with the optional argument in brackets.

The auto-generated value table is appended at the end of the
documentation body.

Because QDoc cannot extract documentation from source files outside
the current project, restrict the search for the C++ enum to the
primary tree only. Make Tree::findNodeByNameAndType() a public
function to enable this.

Fixes: QTBUG-92450
Change-Id: If51c6f392e5f20c12a37c585bfd7ef93f23baa15
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 10 insertions, 2 deletions

diff --git a/src/qdoc/qdoc/src/qdoc/cppcodemarker.cpp b/src/qdoc/qdoc/src/qdoc/cppcodemarker.cpp
index 97560a696..7fb26db0c 100644
--- a/src/qdoc/qdoc/src/qdoc/cppcodemarker.cpp
+++ b/src/qdoc/qdoc/src/qdoc/cppcodemarker.cpp
@@ -292,10 +292,18 @@ QString CppCodeMarker::markedUpName(const Node *node)
 
 QString CppCodeMarker::markedUpEnumValue(const QString &enumValue, const Node *relative)
 {
-    if (!relative->isEnumType())
+    const auto *node = relative->parent();
+
+    if (relative->isQmlProperty()) {
+        const auto *qpn = static_cast<const QmlPropertyNode*>(relative);
+        if (qpn->enumNode() && !enumValue.startsWith("%1."_L1.arg(qpn->enumPrefix())))
+            return "%1<@op>.</@op>%2"_L1.arg(qpn->enumPrefix(), enumValue);
+    }
+
+    if (!relative->isEnumType()) {
         return enumValue;
+    }
 
-    const Node *node = relative->parent();
     QStringList parts;
     while (!node->isHeader() && node->parent()) {
         parts.prepend(markedUpName(node));