qdoc: Allow custom status descriptions for C++, QML types

QDoc already allows defining a custom status for C++ and QML modules
via the \modulestate command. In Qt, this is typically used for
marking a module and its types with 'Technology preview' status.

Allow a custom status for individual types as well, with
\meta {status} {<description>} command. This information is added
to the 'Requisites' table on top of the type reference page.

Document the new status argument for \meta, and update its
documentation as it contained obsolete information.

Pick-to: 6.5
Task-number: QTBUG-113026
Change-Id: I5a13aa8650b6e188ffe50a1e948da90474bfb7a0
Reviewed-by: Luca Di Sera <luca.disera@qt.io>

6 files changed, 37 insertions, 16 deletions

diff --git a/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc
index a915a9f7c..d1a09eb90 100644
--- a/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc
@@ -60,6 +60,7 @@
     \li \l {macro-command} {\\macro}
     \li \l {meta-command} {\\meta}
     \li \l {module-command} {\\module}
+    \li \l {modulestate-command} {\\modulestate}
     \li \l {namespace-command} {\\namespace}
     \li \l {nextpage-command} {\\nextpage}
     \li \l {noautolist-command} {\\noautolist}
diff --git a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 714db3664..e5f25700f 100644
--- a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3802,7 +3802,7 @@
     \target meta-command
     \section1 \\meta
 
-    The \\meta command is used for adding metadata to example documentation.
+    The \\meta command is used for adding metadata to documentation.
     The command has two arguments: the first argument is the name of the
     metadata attribute, and the second argument is the value for the attribute.
     Each argument should be enclosed in curly brackets, as shown in this
@@ -3810,22 +3810,16 @@
 
     \badcode *
     /\1!
-        \class QWidget
-        \brief The QWidget class is the base class of all user interface objects.
+        \example demos/coffee
+        \title Coffee Machine
+        \brief A Qt Quick application with a state-based custom user interface.
 
-        \ingroup basicwidgets
-
-        \meta {technology} {User Interface}
-        \meta {platform} {macOS 10.6}
-        \meta {platform} {MeeGo}
-        \meta {audience} {user}
-        \meta {audience} {programmer}
-        \meta {audience} {designer}
+        \meta {tags} {quick,embedded,states,touch}
+        \meta {category} {Application Examples}
     \1/
     \endcode
 
-    When running QDoc to generate HTML, the example above will have no
-    effect on the generated output.
+    A number of metadata attributes have a specific purpose:
 
     \b {Example Metadata}
 
@@ -3856,7 +3850,7 @@
     file, effectively removing it from Qt Creator's Welcome mode.
 
     \badcode
-    \meta tag broken
+    \meta {tag} {broken}
     \endcode
 
     \b {Example Install Paths}
@@ -3875,6 +3869,21 @@
 
     See also \l {examplesinstallpath}.
 
+    \b {Status}
+
+    A \c status argument for the \\meta command adds a custom status description
+    for a \l {class-command}{\\class} or a \l {qmltype-command}{\\qmltype}. This
+    description will then appear in a table at the top of the type reference page.
+
+    \badcode *
+    /\1!
+        \class QNativeInterface::QAndroidApplication
+        \meta {status} {Android-specific}
+    \1/
+    \endcode
+
+    See also \l {Status}{status-related commands}.
+
     \target noautolist-command
     \section1 \\noautolist
 
diff --git a/src/qdoc/qdoc/generator.cpp b/src/qdoc/qdoc/generator.cpp
index 174cb9c8f..0381040d9 100644
--- a/src/qdoc/qdoc/generator.cpp
+++ b/src/qdoc/qdoc/generator.cpp
@@ -1112,6 +1112,8 @@ QString Generator::formatSince(const Node *node)
 
     If a status description is returned, it is one of:
     \list
+      \li Custom status set explicitly in node's documentation using
+          \c {\meta {status} {<description>}},
       \li 'Deprecated [since <version>]' (\\deprecated [<version>]),
       \li 'Preliminary' (\\preliminary), or
       \li The description adopted from associated module's state:
@@ -1124,7 +1126,9 @@ std::optional<QString> formatStatus(const Node *node, QDocDatabase *qdb)
 {
     QString status;
 
-    if (node->status() == Node::Deprecated) {
+    if (const auto metaMap = node->doc().metaTagMap(); metaMap) {
+        status = metaMap->value("status");
+    } else if (node->status() == Node::Deprecated) {
         status = u"Deprecated"_s;
         if (const auto since = node->deprecatedSince(); !since.isEmpty())
             status += " since %1"_L1.arg(since);
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-type.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-type.xml
index b311f505b..4422b6962 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-type.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-type.xml
@@ -28,6 +28,12 @@
 <db:para><db:link xlink:href="testqdoc-test.xml">Test</db:link></db:para>
 </db:listitem>
 </db:varlistentry>
+<db:varlistentry>
+<db:term>Status:</db:term>
+<db:listitem>
+<db:para>&lt;Work In Progress&gt;</db:para>
+</db:listitem>
+</db:varlistentry>
 </db:variablelist>
 <db:section xml:id="details">
 <db:title>Detailed Description</db:title>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-type.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-type.html
index 389c81b97..d928fbf18 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-type.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-type.html
@@ -27,7 +27,7 @@
 <p>A QML type documented in a .cpp file. <a href="#details">More...</a></p>
 <!-- @@@Type -->
 <div class="table"><table class="alignedsummary" translate="no">
-<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QDoc.Test 1.1</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 1.1</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Instantiates:</td><td class="memItemRight bottomAlign"> <a href="testqdoc-test.html" translate="no">Test</a></td></tr></table></div><ul>
+<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QDoc.Test 1.1</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 1.1</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Instantiates:</td><td class="memItemRight bottomAlign"> <a href="testqdoc-test.html" translate="no">Test</a></td></tr><tr><td class="memItemLeft rightAlign topAlign"> Status:</td><td class="memItemRight bottomAlign"> &lt;Work In Progress&gt;<span class="status work-in-progress"></span></td></tr></table></div><ul>
 <li><a href="qml-qdoc-test-type-members.html">List of all members, including inherited members</a></li>
 <li><a href="qml-qdoc-test-type-obsolete.html">Deprecated members</a></li>
 </ul>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
index 8e4d6e677..f3c9546b8 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
+++ b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
@@ -32,6 +32,7 @@
     \instantiates TestQDoc::Test
     \inqmlmodule QDoc.Test
     \brief A QML type documented in a .cpp file.
+    \meta status { <Work In Progress> }
 */
 
 /*!