From 1d17e5edf2a81a9bcea946fa03ccfe90abf37c8b Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Sat, 4 Mar 2023 22:53:17 +0000
Subject: qdoc: Display individual enum items in \sincelist output

The output of \sincelist command lists enumerations introduced in a
specific version, documented with \enum with an associated \since
meta-command. Individual enum \value entries can also be marked with
a since-clause, however, this information was missing from the
generated list.

Adding support for this is less than trivial because EnumItem is not
a Node subclass, and the Sections class, which is responsible for
distributing the entries displayed in a since-list, operates on
Node instances. To work around this,

  * Introduce since()/setSince() to EnumItem
  * Resolve since info for enum values in Tree::resolveSince()
  * Add enum values to a dedicated map in QDocDatabase
  * Add enum value since attributes to .index file
  * Add 'New Enum Values' as a new Section entry

In order to generate content for the new section, don't directly
populate it; only add a single entry to mark it non-empty. Actual
enum values are then fetched from the new 'since-map'. Entries in
this map contain a pointer to the associated EnumNode, used for
linking.

Add a simple test case in generatedoutput autotest.

Fixes: QTBUG-110781
Change-Id: I064446dc1e369013284ba934adeabe908754b3bb
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
---
 .../scopedenum-docbook/testqdoc-test.xml           |  2 +-
 .../expected_output/scopedenum/testqdoc-test.html  |  2 +-
 .../expected_output/scopedenum/whatsnew.html       | 39 ++++++++++++++++++++++
 .../testdata/scopedenum/scopedenum.qdoc            |  9 ++++-
 .../qdoc/generatedoutput/tst_generatedoutput.cpp   |  5 +--
 5 files changed, 52 insertions(+), 5 deletions(-)
 create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/scopedenum/whatsnew.html

(limited to 'tests/auto/qdoc/generatedoutput')

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum-docbook/testqdoc-test.xml b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum-docbook/testqdoc-test.xml
index b0b7d13bf..5c3cef465 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum-docbook/testqdoc-test.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum-docbook/testqdoc-test.xml
@@ -171,7 +171,7 @@
 </db:tr>
 <db:tr>
 <db:td>
-<db:para><db:code><db:emphasis role="bold"><db:link xlink:href="testqdoc.xml">TestQDoc</db:link></db:emphasis>::<db:emphasis role="bold"><db:link xlink:href="testqdoc-test.xml">Test</db:link></db:emphasis>::<db:emphasis role="bold"><db:link xlink:href="">ScopedEnum</db:link></db:emphasis>::All</db:code></db:para>
+<db:para><db:code><db:emphasis role="bold"><db:link xlink:href="testqdoc.xml">TestQDoc</db:link></db:emphasis>::<db:emphasis role="bold"><db:link xlink:href="testqdoc-test.xml">Test</db:link></db:emphasis>::<db:emphasis role="bold"><db:link xlink:href="">ScopedEnum</db:link></db:emphasis>::All (since Qt 2.0)</db:code></db:para>
 </db:td>
 <db:td><db:code>This | That</db:code></db:td>
 <db:td>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html
index 66bb69623..c6f837f78 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html
@@ -93,7 +93,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr>
 <div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
 <tr><td class="topAlign"><code translate="no">TestQDoc::Test::ScopedEnum::This</code></td><td class="topAlign tblval"><code translate="no">0x01</code></td><td class="topAlign">Something</td></tr>
 <tr><td class="topAlign"><code translate="no">TestQDoc::Test::ScopedEnum::That</code></td><td class="topAlign tblval"><code translate="no">0x02</code></td><td class="topAlign">Something else</td></tr>
-<tr><td class="topAlign"><code translate="no">TestQDoc::Test::ScopedEnum::All</code></td><td class="topAlign tblval"><code translate="no">This | That</code></td><td class="topAlign">Everything</td></tr>
+<tr><td class="topAlign"><code translate="no">TestQDoc::Test::ScopedEnum::All (since Qt 2.0)</code></td><td class="topAlign tblval"><code translate="no">This | That</code></td><td class="topAlign">Everything</td></tr>
 </table></div>
 <p>A scoped enum.</p>
 <!-- @@@ScopedEnum -->
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/whatsnew.html b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/whatsnew.html
new file mode 100644
index 000000000..6d6989f49
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/whatsnew.html
@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- scopedenum.qdoc -->
+  <title>New Classes and Functions | TestCPP</title>
+</head>
+<body>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title">New Classes and Functions</h1>
+<!-- $$$whatsnew.html-description -->
+<div class="descr" id="details">
+<ul>
+<li><a href="#new-namespaces">New Namespaces</a></li>
+<li><a href="#new-classes">New Classes</a></li>
+<li><a href="#new-enum-values">New Enum Values</a></li>
+</ul>
+<h3 id="new-namespaces">New Namespaces</h3>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> namespace </td><td class="memItemRight bottomAlign"><b><a href="testqdoc.html" translate="no">TestQDoc</a></b></td></tr>
+</table></div>
+<h3 id="new-classes">New Classes</h3>
+<div class="flowListDiv" translate="no">
+<dl class="flowList odd"><dt class="alphaChar"><b>D</b></dt>
+<dd><a href="">DontLinkToMe</a></dd>
+</dl>
+<dl class="flowList even"><dt class="alphaChar"><b>T</b></dt>
+<dd><a href="testqdoc-test.html">Test</a> (<a href="testqdoc.html">TestQDoc</a>)</dd>
+<dd><a href="testqdoc-testderived.html">TestDerived</a> (<a href="testqdoc.html">TestQDoc</a>)</dd>
+</dl>
+</div>
+<h3 id="new-enum-values">New Enum Values</h3>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft"> enum value </td><td class="memItemRight"><b><a href="testqdoc-test.html#ScopedEnum-enum">ScopedEnum::All</a></b></td></tr>
+</table></div>
+</div>
+<!-- @@@whatsnew.html -->
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/scopedenum/scopedenum.qdoc b/tests/auto/qdoc/generatedoutput/testdata/scopedenum/scopedenum.qdoc
index 625252486..775e5f81e 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/scopedenum/scopedenum.qdoc
+++ b/tests/auto/qdoc/generatedoutput/testdata/scopedenum/scopedenum.qdoc
@@ -17,7 +17,7 @@
     \value That Something else
     \omitvalue OmittedValue \omit Unused -
                This decription is omitted \endomit
-    \value All  Everything
+    \value [since 2.0] All  Everything
     \omitvalue VeryLastValue
                Nothing here
     \omitvalue UselessValue
@@ -34,3 +34,10 @@
     TestQDoc::Test::ClassicEnum::Howdy does not link,
     but TestQDoc::Test::Howdy might.
 */
+
+/*!
+    \page whatsnew.html
+    \title New Classes and Functions
+
+    \sincelist 2.0
+*/
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index e8aadeffd..3f280e948 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -132,12 +132,12 @@ void tst_generatedOutput::compareLineByLine(const QStringList &expectedFiles)
 
         QFile expectedFile(expected);
         if (!expectedFile.open(QIODevice::ReadOnly))
-            QFAIL("Cannot open expected data file!");
+            QFAIL(qPrintable(QString("Cannot open expected data file: %1").arg(expected)));
         QTextStream expectedIn(&expectedFile);
 
         QFile actualFile(actual);
         if (!actualFile.open(QIODevice::ReadOnly))
-            QFAIL("Cannot open actual data file!");
+            QFAIL(qPrintable(QString("Cannot open actual data file: %1").arg(actual)));
         QTextStream actualIn(&actualFile);
 
         const QLatin1String delim(": ");
@@ -379,6 +379,7 @@ void tst_generatedOutput::scopedEnum()
     testAndCompare("testdata/configs/scopedenum.qdocconf",
                    "scopedenum/testqdoc-test.html "
                    "scopedenum/scoped-enum-linking.html "
+                   "scopedenum/whatsnew.html "
                    "scopedenum-docbook/scoped-enum-linking.xml "
                    "scopedenum-docbook/testqdoc-test.xml");
 }
-- 
cgit v1.2.1