From 046447a6fa686ed076a7df8d27b00abe0811750b Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Tue, 18 Apr 2023 20:44:37 +0000
Subject: qdoc: Add status information to the requisites table for types

QDoc provides various ways to document the status of an entity;
\deprecated, \preliminary, and \modulestate commands. These
commands produce a brief sentence describing the status, however,
for C++ and QML types, a logical place for this information is
also the 'requisites' table at the start of the page.

Having the status information in the table makes it more
apparent for the reader that they're looking at documentation
for a deprecated or preliminary type. For HTML generator, this
commit also adds a <span> element that allows additional
visuals via CSS (e.g. an icon) for a specific status.

Pick-to: 6.5
Fixes: QTBUG-113026
Change-Id: If38a6d51631277a0d98b2cb702acf2598b694643
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
---
 .../docbook/qml-qdoc-test-oldtype.xml              | 36 ++++++++++++++++++++++
 .../docbook/qml-test-nover-typenoversion.xml       |  6 ++++
 .../expected_output/qml-qdoc-test-oldtype.html     | 32 +++++++++++++++++++
 .../qml-test-nover-typenoversion.html              |  2 +-
 .../qdoc/generatedoutput/expected_output/test.qhp  |  7 +++++
 .../expected_output/testtagfile.tags               |  4 +++
 .../qdoc/generatedoutput/testdata/qml/type.cpp     |  7 +++++
 .../qdoc/generatedoutput/tst_generatedoutput.cpp   |  2 ++
 8 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-oldtype.xml
 create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-oldtype.html

(limited to 'tests')

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-oldtype.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-oldtype.xml
new file mode 100644
index 000000000..ce2999582
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-qdoc-test-oldtype.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<db:article xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.2" xml:lang="en">
+<db:info>
+<db:title>OldType QML Type</db:title>
+<db:productname>Test</db:productname>
+<db:titleabbrev>A test project for QDoc build artifacts</db:titleabbrev>
+<db:abstract>
+<db:para>Deprecated old type.</db:para>
+<db:para><db:emphasis role="bold">This type is deprecated since 1.0. We strongly advise against using it in new code.</db:emphasis></db:para>
+<db:para>This type was introduced in Qt 1.1.</db:para>
+</db:abstract>
+</db:info>
+<db:variablelist>
+<db:varlistentry>
+<db:term>Import Statement</db:term>
+<db:listitem>
+<db:para>import QDoc.Test 1.1</db:para>
+</db:listitem>
+</db:varlistentry>
+<db:varlistentry>
+<db:term>Since:</db:term>
+<db:listitem>
+<db:para>Qt 1.1</db:para>
+</db:listitem>
+</db:varlistentry>
+<db:varlistentry>
+<db:term>Status:</db:term>
+<db:listitem>
+<db:para>Deprecated since 1.0</db:para>
+</db:listitem>
+</db:varlistentry>
+</db:variablelist>
+<db:section xml:id="details">
+<db:title>Detailed Description</db:title>
+</db:section>
+</db:article>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-test-nover-typenoversion.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-test-nover-typenoversion.xml
index 676098113..87576add4 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-test-nover-typenoversion.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qml-test-nover-typenoversion.xml
@@ -28,6 +28,12 @@
 <db:para><db:link xlink:href="testqdoc-testderived.xml">TestDerived</db:link></db:para>
 </db:listitem>
 </db:varlistentry>
+<db:varlistentry>
+<db:term>Status:</db:term>
+<db:listitem>
+<db:para>Tech Preview</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-oldtype.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-oldtype.html
new file mode 100644
index 000000000..f314ad331
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-qdoc-test-oldtype.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- type.cpp -->
+  <meta name="description" content="Deprecated old type.">
+  <title>OldType QML Type | Test</title>
+</head>
+<body>
+<li><a href="qdoc-test-qmlmodule.html" translate="no">Types</a></li>
+<li>OldType</li>
+<div class="sidebar">
+<div class="toc">
+<h3 id="toc">Contents</h3>
+<ul>
+<li class="level1"><a href="#details">Detailed Description</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">OldType QML Type</h1>
+<!-- $$$OldType-brief -->
+<p>Deprecated old type. <a href="#details">More...</a></p>
+<!-- @@@OldType -->
+<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"> Status:</td><td class="memItemRight bottomAlign"> Deprecated since 1.0<span class="status deprecated"></span></td></tr></table></div><ul>
+<li><a href="qml-qdoc-test-oldtype-members.html">List of all members, including inherited members</a></li>
+</ul>
+<!-- $$$OldType-description -->
+<h2 id="details">Detailed Description</h2>
+<!-- @@@OldType -->
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qml-test-nover-typenoversion.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-test-nover-typenoversion.html
index 432085d63..b426c95a9 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qml-test-nover-typenoversion.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-test-nover-typenoversion.html
@@ -23,7 +23,7 @@
 <p>Another QML type documented in a .cpp file. <a href="#details">More...</a></p>
 <!-- @@@TypeNoVersion -->
 <div class="table"><table class="alignedsummary" translate="no">
-<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import Test.NoVer</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-testderived.html" translate="no">TestDerived</a></td></tr></table></div><ul>
+<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import Test.NoVer</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-testderived.html" translate="no">TestDerived</a></td></tr><tr><td class="memItemLeft rightAlign topAlign"> Status:</td><td class="memItemRight bottomAlign"> Tech Preview<span class="status tech-preview"></span></td></tr></table></div><ul>
 <li><a href="qml-test-nover-typenoversion-members.html">List of all members, including inherited members</a></li>
 </ul>
 <!-- $$$TypeNoVersion-description -->
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
index 7ef863788..2070d5635 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
+++ b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
@@ -42,6 +42,9 @@
                     <section ref="qml-qdoc-test-doctest.html" title="DocTest Type Reference">
                         <section ref="qml-qdoc-test-doctest-members.html" title="List of all members"/>
                     </section>
+                    <section ref="qml-qdoc-test-oldtype.html" title="OldType Type Reference">
+                        <section ref="qml-qdoc-test-oldtype-members.html" title="List of all members"/>
+                    </section>
                     <section ref="qml-qdoc-test-type.html" title="Type Type Reference">
                         <section ref="qml-qdoc-test-type-members.html" title="List of all members"/>
                         <section ref="qml-qdoc-test-type-obsolete.html" title="Obsolete members"/>
@@ -72,6 +75,8 @@
             <keyword name="DocTest" id="QML.DocTest" ref="qml-qdoc-test-doctest.html"/>
             <keyword name="DocTest" id="QML.QDoc.Test1.DocTest" ref="qml-qdoc-test-doctest.html"/>
             <keyword name="Obsolete Classes" id="Obsolete Classes" ref="obsolete-classes.html"/>
+            <keyword name="OldType" id="QML.OldType" ref="qml-qdoc-test-oldtype.html"/>
+            <keyword name="OldType" id="QML.QDoc.Test1.OldType" ref="qml-qdoc-test-oldtype.html"/>
             <keyword name="ProgressBar" id="QML.ProgressBar" ref="qml-uicomponents-progressbar.html"/>
             <keyword name="ProgressBar" id="QML.UIComponents1.ProgressBar" ref="qml-uicomponents-progressbar.html"/>
             <keyword name="QDOCTEST_MACRO" id="QDOCTEST_MACRO" ref="testqdoc.html#QDOCTEST_MACRO"/>
@@ -172,6 +177,8 @@
             <file>qml-qdoc-test-child.html</file>
             <file>qml-qdoc-test-doctest-members.html</file>
             <file>qml-qdoc-test-doctest.html</file>
+            <file>qml-qdoc-test-oldtype-members.html</file>
+            <file>qml-qdoc-test-oldtype.html</file>
             <file>qml-qdoc-test-type-members.html</file>
             <file>qml-qdoc-test-type-obsolete.html</file>
             <file>qml-qdoc-test-type.html</file>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
index 891909786..729ced4c0 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
@@ -86,6 +86,10 @@
             <arglist>(bool really)</arglist>
         </member>
     </compound>
+    <compound kind="class">
+        <name>QDoc.Test.OldType</name>
+        <filename>qml-qdoc-test-oldtype.html</filename>
+    </compound>
     <compound kind="class">
         <name>UIComponents.ProgressBar</name>
         <filename>qml-uicomponents-progressbar.html</filename>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
index f0d913853..8e4d6e677 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
+++ b/tests/auto/qdoc/generatedoutput/testdata/qml/type.cpp
@@ -41,6 +41,13 @@
     \brief Another QML type documented in a .cpp file.
 */
 
+/*!
+    \qmltype OldType
+    \inqmlmodule QDoc.Test
+    \brief Deprecated old type.
+    \deprecated [1.0]
+*/
+
 /*!
     \qmlproperty int Type::id
     \readonly
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 552ed39cc..f39a87223 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -242,6 +242,7 @@ void tst_generatedOutput::htmlFromQml()
                    "qml-qdoc-test-type-members.html "
                    "qml-qdoc-test-type-obsolete.html "
                    "qml-qdoc-test-type.html "
+                   "qml-qdoc-test-oldtype.html "
                    "qml-test-nover-typenoversion.html "
                    "qml-test-nover-typenoversion-members.html "
                    "qml-uicomponents-progressbar.html "
@@ -332,6 +333,7 @@ void tst_generatedOutput::docBookFromQml()
                    "docbook/qml-qdoc-test-yetanotherchild.xml "
                    "docbook/qml-qdoc-test-doctest.xml "
                    "docbook/qml-qdoc-test-type.xml "
+                   "docbook/qml-qdoc-test-oldtype.xml "
                    "docbook/qml-test-nover-typenoversion.xml "
                    "docbook/qml-uicomponents-progressbar.xml "
                    "docbook/qml-uicomponents-switch.xml "
-- 
cgit v1.2.1