Don't let CMD_VALUE break CMD_TABLE6.5

In QDoc, if a `\table` command follows a (list of) `\value` command(s), the content of both commands is merged in QDoc's HTML output. This means the table ends up broken. A workaround exists, which is to add a `\br` command to insert an explicit line break after the `\value` entry. This (mis-)behavior was discovered in the documentation for Qt Quick's `Image.fillMode` enumeration (see related Jira issue in the Task-Number footer. The responsible class in QDoc is DocParser. In the handling of `CMD_TABLE`, there's no call to `DocParser::leaveValueList()`, as is a recurring pattern in four other contexts of DocParser's command handling: - After the while/switch in `Docparser::parse()` - presumably an attempt at ensuring it's always called, that doesn't seem to work satisfactory. - At the start of `DocParser::startSection`. - In a conditional at the top of `DocParser::startPara`. - At the start of handling `CMD_IMAGE`. This patch adds a test case in tst_generatedOutput that reproduces the circumstances in which the issue could present itself. QDoc is modified by adding a call to `DocParser::leaveValueList() upon entering the code responsible for handling `CMD_TABLE` ensures correct behavior, where HTML for the value list is terminated properly before creating the new table for the table command. Task-number: QTBUG-115537 Fixes: QTBUG-115720 Change-Id: I06c9c25b4ff792621d56e5eb802178cfd376f8c3 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> (cherry picked from commit 23fd844bf85f1742751b960fd32e8da4e16fc793) Reviewed-by: Paul Wicking <paul.wicking@qt.io>
author: Paul Wicking <paul.wicking@qt.io> 2023-08-08 12:28:28 +0200
committer: Paul Wicking <paul.wicking@qt.io> 2023-10-15 19:11:00 +0200
commit: 6417a2ff270cd9e2651d4f2ffd71e380babc4827 (patch)
tree: 973406c5947bfe3ea53118e05e36dd24990444be
parent: e714badd9673b49859c2448e9432a4dea311f240 (diff)
10 files changed, 257 insertions, 0 deletions
diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp
index 0ca616577..19cd75bb0 100644
--- a/src/qdoc/docparser.cpp
+++ b/src/qdoc/docparser.cpp
@@ -943,6 +943,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate,
                     startFormat(ATOM_FORMATTING_SUPERSCRIPT, cmd);
                     break;
                 case CMD_TABLE:
+                    leaveValueList();
                     p1 = getOptionalArgument();
                     p2 = getOptionalArgument();
                     if (openCommand(cmd)) {
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue-members.html b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue-members.html
new file mode 100644
index 000000000..328848c33
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue-members.html
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- table-after-value.cpp -->
+  <meta name="description" content="Test that the \table command can follow a \value command.">
+  <title>List of All Members for TableAfterValue | TableAfterValue</title>
+</head>
+<body>
+<li>TableAfterValue</li>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">List of All Members for TableAfterValue</h1>
+<p>This is the complete list of members for <a href="tableaftervalue.html">TableAfterValue</a>, including inherited members.</p>
+<ul>
+<li class="fn" translate="no">enum <span class="name"><b><a href="tableaftervalue.html#Reproduces-enum" translate="no">Reproduces</a></b></span></li>
+</ul>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.html b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.html
new file mode 100644
index 000000000..d27d77ef6
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.html
@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- table-after-value.cpp -->
+  <meta name="description" content="Test that the \table command can follow a \value command.">
+  <title>TableAfterValue Class | TableAfterValue</title>
+</head>
+<body>
+<li>TableAfterValue</li>
+<div class="sidebar">
+<div class="toc">
+<h3 id="toc">Contents</h3>
+<ul>
+<li class="level1"><a href="#public-types">Public Types</a></li>
+<li class="level1"><a href="#details">Detailed Description</a></li>
+<li class="level2"><a href="#background-for-this-test-content">Background for this test content</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">TableAfterValue Class</h1>
+<!-- $$$TableAfterValue-brief -->
+<p>Test that the \table command can follow a \value command. <a href="#details">More...</a></p>
+<!-- @@@TableAfterValue -->
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include &lt;TableAfterValue&gt;</span></td></tr>
+</table></div>
+<ul>
+<li><a href="tableaftervalue-members.html">List of all members, including inherited members</a></li>
+</ul>
+<h2 id="public-types">Public Types</h2>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="tableaftervalue.html#Reproduces-enum" translate="no">Reproduces</a></b> { Problem }</td></tr>
+</table></div>
+<!-- $$$TableAfterValue-description -->
+<div class="descr">
+<h2 id="details">Detailed Description</h2>
+<h3 id="background-for-this-test-content">Background for this test content</h3>
+<p>According to QTBUG-115720, whenever a \value is followed by \table, the contents of the two commands end up being merged. This is likely surprising. The bug report suggests a workaround, which is adding \br between \value and \table.</p>
+</div>
+<p><b>See also </b><a href="tableaftervalue.html#Reproduces-enum" translate="no">TableAfterValue::Reproduces</a>.</p>
+<!-- @@@TableAfterValue -->
+<div class="types">
+<h2>Member Type Documentation</h2>
+<!-- $$$Reproduces$$$Problem -->
+<h3 class="fn" translate="no" id="Reproduces-enum">enum TableAfterValue::<span class="name">Reproduces</span></h3>
+<div class="table"><table class="valuelist"><tr><th class="tblConst">Constant</th><th class="tblVal">Value</th></tr>
+<tr><td class="topAlign"><code translate="no">TableAfterValue::Problem</code></td><td class="topAlign tblval"><code translate="no">0</code></td></tr>
+</table></div>
+<div class="table"><table class="generic">
+ <tr valign="top" class="odd"><td >This table shouldn't be mangled by the previous \value command.</td></tr>
+</table></div>
+<!-- @@@Reproduces -->
+</div>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.index b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.index
new file mode 100644
index 000000000..4f3164508
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.index
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE QDOCINDEX>
+<INDEX url="" title="TableAfterValue Reference Documentation" version="" project="TableAfterValue">
+    <namespace name="" status="active" access="public" module="tableaftervalue">
+        <class name="TableAfterValue" href="tableaftervalue.html" status="active" access="public" location="table-after-value.h" documented="true" module="Test" brief="Test that the \table command can follow a \value command">
+            <contents name="background-for-this-test-content" title="Background for this test content" level="1"/>
+            <enum name="Reproduces" fullname="TableAfterValue::Reproduces" href="tableaftervalue.html#Reproduces-enum" status="active" access="public" location="table-after-value.h" documented="true">
+                <value name="Problem" value="0"/>
+            </enum>
+        </class>
+        <module name="Test" href="test-module.html" status="internal" seen="false" title=""/>
+    </namespace>
+</INDEX>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.webxml b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.webxml
new file mode 100644
index 000000000..9f7f5e3bb
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.webxml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<WebXML>
+    <document>
+        <class name="TableAfterValue" href="tableaftervalue.html" status="active" access="public" location="table-after-value.h" documented="true" module="Test" brief="Test that the \table command can follow a \value command">
+            <contents name="background-for-this-test-content" title="Background for this test content" level="1"/>
+            <description>
+                <brief>Test that the \table command can follow a \value command.</brief>
+                <section id="background-for-this-test-content">
+                    <heading level="1">Background for this test content</heading>
+                    <para>According to QTBUG-115720, whenever a \value is followed by \table, the contents of the two commands end up being merged. This is likely surprising. The bug report suggests a workaround, which is adding \br between \value and \table.</para>
+                </section>
+                <see-also>
+                    <link raw="TableAfterValue::Reproduces" href="tableaftervalue.html#Reproduces-enum" type="enum" enum="TableAfterValue::Reproduces">TableAfterValue::Reproduces</link>
+                </see-also>
+            </description>
+            <enum name="Reproduces" fullname="TableAfterValue::Reproduces" href="tableaftervalue.html#Reproduces-enum" status="active" access="public" location="table-after-value.h" documented="true">
+                <value name="Problem" value="0"/>
+                <description>
+                    <list type="enum">
+                        <definition>
+                            <term>TableAfterValue::Problem</term>Problem</definition>
+                        <item/>
+                    </list>
+                    <table>
+                        <row>
+                            <item>
+                                <para>This table shouldn't be mangled by the previous \value command.</para>
+                            </item>
+                        </row>
+                    </table>
+                </description>
+            </enum>
+        </class>
+    </document>
+</WebXML>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.xml b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.xml
new file mode 100644
index 000000000..4200e522e
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.xml
@@ -0,0 +1,70 @@
+<?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>TableAfterValue Class</db:title>
+<db:productname>TableAfterValue</db:productname>
+<db:titleabbrev>TableAfterValue Reference Documentation</db:titleabbrev>
+<db:abstract>
+<db:para>Test that the \table command can follow a \value command.</db:para>
+</db:abstract>
+</db:info>
+<db:variablelist>
+<db:varlistentry>
+<db:term>Header</db:term>
+<db:listitem>
+<db:para>TableAfterValue</db:para>
+</db:listitem>
+</db:varlistentry>
+</db:variablelist>
+<db:section xml:id="details">
+<db:title>Detailed Description</db:title>
+<db:section xml:id="background-for-this-test-content">
+<db:title>Background for this test content</db:title>
+<db:para>According to QTBUG-115720, whenever a \value is followed by \table, the contents of the two commands end up being merged. This is likely surprising. The bug report suggests a workaround, which is adding \br between \value and \table.</db:para>
+</db:section>
+<db:section>
+<db:title>See Also</db:title>
+<db:para><db:emphasis>See also </db:emphasis>
+<db:simplelist type="vert" role="see-also">
+<db:member><db:link xlink:href="tableaftervalue.xml#Reproduces-enum">TableAfterValue::Reproduces</db:link></db:member>
+</db:simplelist>
+</db:para>
+</db:section>
+</db:section>
+<db:section xml:id="member-type-documentation">
+<db:title>Member Type Documentation</db:title>
+<db:section xml:id="Reproduces-enum">
+<db:title>enum TableAfterValue::Reproduces</db:title>
+<db:enumsynopsis>
+<db:enumname>Reproduces</db:enumname>
+<db:enumitem>
+<db:enumidentifier>Problem</db:enumidentifier>
+<db:enumvalue>0</db:enumvalue>
+</db:enumitem>
+<db:synopsisinfo role="access">public</db:synopsisinfo>
+<db:synopsisinfo role="status">active</db:synopsisinfo>
+<db:synopsisinfo role="threadsafeness">unspecified</db:synopsisinfo>
+</db:enumsynopsis>
+<db:informaltable>
+<db:thead>
+<db:tr>
+<db:th>Constant</db:th>
+</db:tr>
+</db:thead>
+<db:tr>
+<db:td>
+<db:para><db:code><db:emphasis role="bold"><db:link xlink:href="tableaftervalue.xml">TableAfterValue</db:link></db:emphasis>::Problem</db:code></db:para>
+</db:td>
+<db:td><db:code>0</db:code></db:td>
+</db:tr>
+</db:informaltable>
+<db:informaltable style="generic">
+<db:tr valign="top">
+<db:td>
+<db:para>This table shouldn't be mangled by the previous \value command.</db:para>
+</db:td>
+</db:tr>
+</db:informaltable>
+</db:section>
+</db:section>
+</db:article>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.cpp b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.cpp
new file mode 100644
index 000000000..f97118194
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.cpp
@@ -0,0 +1,28 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+#include "tableaftervalue.h"
+
+/*!
+    \class TableAfterValue
+    \inmodule Test
+    \brief Test that the \\table command can follow a \\value command.
+
+    \section1 Background for this test content
+    According to QTBUG-115720, whenever a \\value is followed by \\table, the
+    contents of the two commands end up being merged. This is likely surprising.
+    The bug report suggests a workaround, which is adding \\br between \\value
+    and \\table.
+
+    \sa TableAfterValue::Reproduces
+*/
+
+/*!
+    \enum TableAfterValue::Reproduces
+
+    \value Problem
+
+    \table
+    \row
+    \li This table shouldn't be mangled by the previous \\value command.
+    \endtable
+*/
diff --git a/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.h b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.h
new file mode 100644
index 000000000..d667bb06b
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.h
@@ -0,0 +1,8 @@
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+class TableAfterValue
+{
+public:
+    enum Reproduces { Problem };
+};
diff --git a/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.qdocconf
new file mode 100644
index 000000000..ad64da0ab
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/tables/table-after-value.qdocconf
@@ -0,0 +1,17 @@
+include(../configs/config.qdocconf)
+project = TableAfterValue
+
+headerdirs  = .
+sourcedirs  = .
+exampledirs = .
+
+outputformats             = WebXML HTML DocBook
+WebXML.quotinginformation = true
+WebXML.nosubdirs          = true
+WebXML.outputsubdir = tableaftervalue
+
+HTML.nosubdirs = true
+HTML.outputsubdir = tableaftervalue
+
+DocBook.nosubdirs = true
+DocBook.outputsubdir = tableaftervalue
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 44210e0ab..7e486e58f 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -57,6 +57,7 @@ private slots:
     void testTagFile();
     void testGlobalFunctions();
     void proxyPage();
+    void tableAfterValue();
 
 private:
     QScopedPointer<QTemporaryDir> m_outputDir;
@@ -301,6 +302,16 @@ void tst_generatedOutput::illformated_documentation_caused_qtbug112641()
                    "html/illformatteddocumentation.index");
 }
 
+void tst_generatedOutput::tableAfterValue()
+{
+    testAndCompare("testdata/tables/table-after-value.qdocconf",
+                   "tableaftervalue/tableaftervalue-members.html "
+                   "tableaftervalue/tableaftervalue.html "
+                   "tableaftervalue/tableaftervalue.index "
+                   "tableaftervalue/tableaftervalue.webxml "
+                   "tableaftervalue/tableaftervalue.xml");
+}
+
 void tst_generatedOutput::docBookFromQDocFile()
 {
     testAndCompare("testdata/configs/docbook_test.qdocconf",
author	Paul Wicking <paul.wicking@qt.io>	2023-08-08 12:28:28 +0200
committer	Paul Wicking <paul.wicking@qt.io>	2023-10-15 19:11:00 +0200
commit	6417a2ff270cd9e2651d4f2ffd71e380babc4827 (patch)
tree	973406c5947bfe3ea53118e05e36dd24990444be
parent	e714badd9673b49859c2448e9432a4dea311f240 (diff)