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, 36 insertions, 0 deletions

diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/qmlenumvaluesfromcpp/class.cpp b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/qmlenumvaluesfromcpp/class.cpp
new file mode 100644
index 000000000..fa3cc1e31
--- /dev/null
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/qmlenumvaluesfromcpp/class.cpp
@@ -0,0 +1,36 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
+
+#include "class.h"
+
+/*!
+    \module Module
+*/
+
+/*!
+    \class Class
+    \inmodule Module
+*/
+
+/*!
+    \enum Class::Values
+
+    Try now these exciting values in your C++ code:
+
+    \value One
+           One value
+
+    Wait, that's not all!
+
+    \value Two
+           2nd value
+    \value Three
+           3rd value
+*/
+
+/*!
+    \enum Class::MoreValues
+
+    \value Something something
+    \value Else entirely
+*/