From a7b63a0905b149168099ec8b046eca07d8f70f6b Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Wed, 6 Jan 2021 23:05:31 +0100
Subject: qdoc: Fix Section::reduce() omitting sections with obsolete members

This caused documentation for obsolete members to go missing if a
section had only obsolete members.

Task-number: QTBUG-89003
Change-Id: I9fb38bb76af45eda42cddc25bb4f6137e73e6fc3
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 19002292a73d502da9ab4da168b8509cda1d6908)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 .../docbook/testqdoc-testderived.xml               | 24 ++++++++++++++++++++++
 .../expected_output/dontdocument/dontdocument.qhp  |  3 +++
 .../html/testqdoc-testderived.webxml               |  5 +++++
 .../properties-docbook/testqdoc-testderived.xml    | 24 ++++++++++++++++++++++
 .../expected_output/properties/testcpp.index       |  1 +
 .../properties/testqdoc-testderived.html           |  1 +
 .../qdoc/generatedoutput/expected_output/test.qhp  |  3 +++
 .../generatedoutput/expected_output/testcpp.index  |  1 +
 .../testqdoc-testderived-obsolete.html             | 24 ++++++++++++++++++++++
 .../expected_output/testqdoc-testderived.html      |  1 +
 .../expected_output/testtagfile.tags               |  7 +++++++
 .../generatedoutput/testdata/testcpp/testcpp.cpp   | 10 +++++++++
 .../generatedoutput/testdata/testcpp/testcpp.h     |  1 +
 .../qdoc/generatedoutput/tst_generatedoutput.cpp   |  1 +
 14 files changed, 106 insertions(+)
 create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-obsolete.html

(limited to 'tests')

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/testqdoc-testderived.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/testqdoc-testderived.xml
index 7eab0d120..c0846867d 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/testqdoc-testderived.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/testqdoc-testderived.xml
@@ -81,4 +81,28 @@
 </db:methodsynopsis>
 <db:para>Reimplements: <db:link xlink:href="testqdoc-test.xml#virtualFun" type="function">Test::virtualFun()</db:link>.</db:para>
 </db:section>
+<db:section xml:id="obsolete">
+<db:title>Obsolete Members for TestDerived</db:title>
+<db:para><db:emphasis role="bold">The following members of class <db:link xlink:href="testqdoc-testderived.xml">TestDerived</db:link> are obsolete.</db:emphasis> They are provided to keep old source code working. We strongly advise against using them in new code.</db:para>
+<db:section xml:id="member-function-documentation">
+<db:title>Member Function Documentation</db:title>
+<db:section xml:id="staticObsoleteMember">
+<db:title>[static] TestDerived::void staticObsoleteMember()</db:title>
+<db:methodsynopsis>
+<db:modifier>static</db:modifier>
+<db:void/>
+<db:methodname>staticObsoleteMember</db:methodname>
+<db:void/>
+<db:synopsisinfo db:role="meta">plain</db:synopsisinfo>
+<db:synopsisinfo db:role="signature">void staticObsoleteMember()</db:synopsisinfo>
+<db:synopsisinfo db:role="access">public</db:synopsisinfo>
+<db:synopsisinfo db:role="status">obsolete</db:synopsisinfo>
+<db:synopsisinfo db:role="threadsafeness">unspecified</db:synopsisinfo>
+<db:synopsisinfo db:role="module">TestCPP</db:synopsisinfo>
+</db:methodsynopsis>
+<db:para>This function is obsolete. It is provided to keep old source code working. We strongly advise against using it in new code.</db:para>
+<db:para>Static obsolete method.</db:para>
+</db:section>
+</db:section>
+</db:section>
 </db:section></db:article>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
index 7efcc1e8d..3cc86e329 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
+++ b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
@@ -14,6 +14,7 @@
                     </section>
                     <section ref="testqdoc-testderived.html" title="TestQDoc::TestDerived Class Reference">
                         <section ref="testqdoc-testderived-members.html" title="List of all members"/>
+                        <section ref="testqdoc-testderived-obsolete.html" title="Obsolete members"/>
                     </section>
                 </section>
             </section>
@@ -40,6 +41,7 @@
             <keyword name="overload" id="Test::overload" ref="testqdoc-test.html#overload"/>
             <keyword name="someFunction" id="Test::someFunction" ref="testqdoc-test.html#someFunction"/>
             <keyword name="someFunctionDefaultArg" id="Test::someFunctionDefaultArg" ref="testqdoc-test.html#someFunctionDefaultArg"/>
+            <keyword name="staticObsoleteMember" id="TestDerived::staticObsoleteMember" ref="testqdoc-testderived-obsolete.html#staticObsoleteMember"/>
             <keyword name="virtualFun" id="Test::virtualFun" ref="testqdoc-test.html#virtualFun"/>
             <keyword name="virtualFun" id="TestDerived::virtualFun" ref="testqdoc-testderived.html#virtualFun"/>
         </keywords>
@@ -51,6 +53,7 @@
             <file>testqdoc-test-obsolete.html</file>
             <file>testqdoc-test.html</file>
             <file>testqdoc-testderived-members.html</file>
+            <file>testqdoc-testderived-obsolete.html</file>
             <file>testqdoc-testderived.html</file>
             <file>testqdoc.html</file>
         </files>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/testqdoc-testderived.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/testqdoc-testderived.webxml
index fdcbb4649..099f20dce 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/testqdoc-testderived.webxml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/testqdoc-testderived.webxml
@@ -5,6 +5,11 @@
             <description>
                 <brief>A derived class in a namespace.</brief>
             </description>
+            <function name="staticObsoleteMember" fullname="TestQDoc::TestDerived::staticObsoleteMember" href="testqdoc-testderived-obsolete.html#staticObsoleteMember" status="obsolete" access="public" location="testcpp.h" documented="true" meta="plain" virtual="non" const="false" static="true" final="false" override="false" type="void" signature="void staticObsoleteMember()">
+                <description>
+                    <para>Static obsolete method.</para>
+                </description>
+            </function>
             <function name="virtualFun" fullname="TestQDoc::TestDerived::virtualFun" href="testqdoc-testderived.html#virtualFun" status="active" access="public" location="testcpp.h" documented="true" meta="plain" virtual="virtual" const="false" static="false" final="false" override="true" type="void" signature="void virtualFun() override">
                 <description/>
             </function>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties-docbook/testqdoc-testderived.xml b/tests/auto/qdoc/generatedoutput/expected_output/properties-docbook/testqdoc-testderived.xml
index 68a043595..b38e08f5e 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/properties-docbook/testqdoc-testderived.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/properties-docbook/testqdoc-testderived.xml
@@ -197,4 +197,28 @@
 </db:methodsynopsis>
 <db:para>Reimplements: <db:link xlink:href="testqdoc-test.xml#virtualFun" type="function">Test::virtualFun()</db:link>.</db:para>
 </db:section>
+<db:section xml:id="obsolete">
+<db:title>Obsolete Members for TestDerived</db:title>
+<db:para><db:emphasis role="bold">The following members of class <db:link xlink:href="testqdoc-testderived.xml">TestDerived</db:link> are obsolete.</db:emphasis> They are provided to keep old source code working. We strongly advise against using them in new code.</db:para>
+<db:section xml:id="member-function-documentation">
+<db:title>Member Function Documentation</db:title>
+<db:section xml:id="staticObsoleteMember">
+<db:title>[static] TestDerived::void staticObsoleteMember()</db:title>
+<db:methodsynopsis>
+<db:modifier>static</db:modifier>
+<db:void/>
+<db:methodname>staticObsoleteMember</db:methodname>
+<db:void/>
+<db:synopsisinfo db:role="meta">plain</db:synopsisinfo>
+<db:synopsisinfo db:role="signature">void staticObsoleteMember()</db:synopsisinfo>
+<db:synopsisinfo db:role="access">public</db:synopsisinfo>
+<db:synopsisinfo db:role="status">obsolete</db:synopsisinfo>
+<db:synopsisinfo db:role="threadsafeness">unspecified</db:synopsisinfo>
+<db:synopsisinfo db:role="module">TestCPP</db:synopsisinfo>
+</db:methodsynopsis>
+<db:para>This function is obsolete. It is provided to keep old source code working. We strongly advise against using it in new code.</db:para>
+<db:para>Static obsolete method.</db:para>
+</db:section>
+</db:section>
+</db:section>
 </db:section></db:article>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
index 7d8f0c5eb..2566c1fc9 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
+++ b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
@@ -79,6 +79,7 @@
                 </function>
                 <function name="someBindableProp" fullname="TestQDoc::TestDerived::someBindableProp" href="testqdoc-testderived.html#someBindableProp" status="internal" access="private" location="testcpp.h" meta="plain" virtual="non" const="false" static="false" final="false" override="false" type="QBindable&lt;QString&gt;" signature="QBindable&lt;QString&gt; someBindableProp()"/>
                 <function name="someProp" fullname="TestQDoc::TestDerived::someProp" href="testqdoc-testderived.html#someProp-prop" status="active" access="public" location="testcpp.h" meta="plain" virtual="non" const="false" static="false" final="false" override="false" associated-property="someProp" type="const QString &amp;" signature="const QString &amp; someProp()"/>
+                <function name="staticObsoleteMember" fullname="TestQDoc::TestDerived::staticObsoleteMember" href="testqdoc-testderived-obsolete.html#staticObsoleteMember" status="obsolete" access="public" location="testcpp.h" documented="true" meta="plain" virtual="non" const="false" static="true" final="false" override="false" type="void" signature="void staticObsoleteMember()"/>
                 <function name="virtualFun" fullname="TestQDoc::TestDerived::virtualFun" href="testqdoc-testderived.html#virtualFun" status="active" access="public" location="testcpp.h" documented="true" meta="plain" virtual="virtual" const="false" static="false" final="false" override="true" type="void" signature="void virtualFun() override"/>
                 <struct name="QPrivateSignal" fullname="TestQDoc::TestDerived::QPrivateSignal" href="testqdoc-testderived-qprivatesignal.html" status="internal" access="private" location="testcpp.h"/>
                 <typedef name="DerivedType" fullname="TestQDoc::TestDerived::DerivedType" href="testqdoc-testderived.html#DerivedType-typedef" status="active" access="public" location="testcpp.h" documented="true" aliasedtype="Test::SomeType"/>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived.html b/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived.html
index 8b2ed3e73..f0f43e32a 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/properties/testqdoc-testderived.html
@@ -31,6 +31,7 @@
 </td></tr><tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 COMPONENTS QDocTest REQUIRED) <br/>
 target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += testcpp</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <a href="testqdoc-test.html">TestQDoc::Test</a></td></tr></table></div><ul>
 <li><a href="testqdoc-testderived-members.html">List of all members, including inherited members</a></li>
+<li><a href="testqdoc-testderived-obsolete.html">Obsolete members</a></li>
 </ul>
 <a name="public-types"></a>
 <h2 id="public-types">Public Types</h2>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
index 9bd9cd5ad..59ccb7059 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
+++ b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
@@ -25,6 +25,7 @@
                     </section>
                     <section ref="testqdoc-testderived.html" title="TestQDoc::TestDerived Class Reference">
                         <section ref="testqdoc-testderived-members.html" title="List of all members"/>
+                        <section ref="testqdoc-testderived-obsolete.html" title="Obsolete members"/>
                     </section>
                 </section>
                 <section ref="uicomponents-qmlmodule.html" title="QML Types">
@@ -124,6 +125,7 @@
             <keyword name="secondColor" id="ProgressBar::secondColor" ref="qml-uicomponents-progressbar.html#secondColor-prop"/>
             <keyword name="someFunction" id="Test::someFunction" ref="testqdoc-test.html#someFunction"/>
             <keyword name="someFunctionDefaultArg" id="Test::someFunctionDefaultArg" ref="testqdoc-test.html#someFunctionDefaultArg"/>
+            <keyword name="staticObsoleteMember" id="TestDerived::staticObsoleteMember" ref="testqdoc-testderived-obsolete.html#staticObsoleteMember"/>
             <keyword name="toggle" id="Switch::toggle" ref="qml-uicomponents-switch.html#toggle-method"/>
             <keyword name="type" id="Type::type" ref="qml-qdoc-test-type.html#type-attached-prop"/>
             <keyword name="value" id="ProgressBar::value" ref="qml-uicomponents-progressbar.html#value-prop"/>
@@ -168,6 +170,7 @@
             <file>testqdoc-test-obsolete.html</file>
             <file>testqdoc-test.html</file>
             <file>testqdoc-testderived-members.html</file>
+            <file>testqdoc-testderived-obsolete.html</file>
             <file>testqdoc-testderived.html</file>
             <file>testqdoc.html</file>
             <file>uicomponents-qmlmodule.html</file>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
index 52fcf654b..3d2752435 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
@@ -48,6 +48,7 @@
                 <typedef name="SomeType" fullname="TestQDoc::Test::SomeType" href="testqdoc-test.html#SomeType-typedef" status="active" access="public" location="testcpp.h" documented="true"/>
             </class>
             <class name="TestDerived" fullname="TestQDoc::TestDerived" href="testqdoc-testderived.html" status="active" access="public" location="testcpp.h" documented="true" bases="TestQDoc::Test" module="TestCPP" brief="A derived class in a namespace">
+                <function name="staticObsoleteMember" fullname="TestQDoc::TestDerived::staticObsoleteMember" href="testqdoc-testderived-obsolete.html#staticObsoleteMember" status="obsolete" access="public" location="testcpp.h" documented="true" meta="plain" virtual="non" const="false" static="true" final="false" override="false" type="void" signature="void staticObsoleteMember()"/>
                 <function name="virtualFun" fullname="TestQDoc::TestDerived::virtualFun" href="testqdoc-testderived.html#virtualFun" status="active" access="public" location="testcpp.h" documented="true" meta="plain" virtual="virtual" const="false" static="false" final="false" override="true" type="void" signature="void virtualFun() override"/>
                 <typedef name="DerivedType" fullname="TestQDoc::TestDerived::DerivedType" href="testqdoc-testderived.html#DerivedType-typedef" status="active" access="public" location="testcpp.h" documented="true" aliasedtype="Test::SomeType"/>
                 <typedef name="NotTypedef" fullname="TestQDoc::TestDerived::NotTypedef" href="testqdoc-testderived.html#NotTypedef-typedef" status="active" access="public" location="testcpp.h" documented="true" aliasedtype="int"/>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-obsolete.html b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-obsolete.html
new file mode 100644
index 000000000..eea2e5310
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived-obsolete.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- testcpp.cpp -->
+  <title>Obsolete Members for TestDerived | TestCPP</title>
+</head>
+<body>
+<li>TestDerived</li>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title">Obsolete Members for TestDerived</h1>
+<p><b>The following members of class <a href="testqdoc-testderived.html">TestDerived</a> are obsolete.</b> They are provided to keep old source code working. We strongly advise against using them in new code.</p>
+<h2>Static Public Members</h2>
+<div class="table"><table class="alignedsummary">
+<tr><td class="memItemLeft topAlign rightAlign"> <code>(obsolete) </code>void </td><td class="memItemRight bottomAlign"><b><a href="testqdoc-testderived.html#staticObsoleteMember">staticObsoleteMember</a></b>()</td></tr>
+</table></div>
+<h2>Member Function Documentation</h2>
+<!-- $$$staticObsoleteMember[overload1]$$$staticObsoleteMember -->
+<h3 class="fn" id="staticObsoleteMember"><a name="staticObsoleteMember"></a><code>[static] </code><span class="type">void</span> TestDerived::<span class="name">staticObsoleteMember</span>()</h3>
+<p>This function is obsolete. It is provided to keep old source code working. We strongly advise against using it in new code.</p>
+<p>Static obsolete method.</p>
+<!-- @@@staticObsoleteMember -->
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived.html b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived.html
index 88d232148..e81391d5c 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-testderived.html
@@ -27,6 +27,7 @@
 </td></tr><tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 COMPONENTS QDocTest REQUIRED) <br/>
 target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += testcpp</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <a href="testqdoc-test.html">TestQDoc::Test</a></td></tr></table></div><ul>
 <li><a href="testqdoc-testderived-members.html">List of all members, including inherited members</a></li>
+<li><a href="testqdoc-testderived-obsolete.html">Obsolete members</a></li>
 </ul>
 <a name="public-types"></a>
 <h2 id="public-types">Public Types</h2>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
index de151f1b3..99b8fb2e1 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testtagfile.tags
@@ -231,6 +231,13 @@
             <anchor>virtualFun</anchor>
             <arglist>() override</arglist>
         </member>
+        <member kind="function" protection="public" virtualness="non" static="yes">
+            <type>void</type>
+            <name>staticObsoleteMember</name>
+            <anchorfile>testqdoc-testderived-obsolete.html</anchorfile>
+            <anchor>staticObsoleteMember</anchor>
+            <arglist>()</arglist>
+        </member>
     </compound>
     <compound kind="class">
         <name>QDoc.Test.Type</name>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp
index af384f35d..51ae743db 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp
+++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.cpp
@@ -232,6 +232,16 @@ void TestDerived::virtualFun()
     I'm an alias, not a typedef.
 */
 
+/*!
+    \obsolete
+
+    Static obsolete method.
+*/
+void TestDerived::staticObsoleteMember()
+{
+    return;
+}
+
 /*!
 \if defined(test_properties)
     \fn void TestDerived::emitSomething()
diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h
index bf5ed89de..800858ca0 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h
+++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/testcpp.h
@@ -97,6 +97,7 @@ public:
     using DerivedType = Test::SomeType;
     using NotTypedef = int;
     void virtualFun() override;
+    static void staticObsoleteMember();
 #ifdef test_properties
     QBindable<QString> bindableProp();
     QBindable<QString> someBindableProp();
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 2f463e559..4ac2ce290 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -237,6 +237,7 @@ void tst_generatedOutput::htmlFromCpp()
                    "testqdoc-test-members.html "
                    "testqdoc-testderived.html "
                    "testqdoc-testderived-members.html "
+                   "testqdoc-testderived-obsolete.html "
                    "testqdoc.html");
 }
 
-- 
cgit v1.2.3