diff options
author | Paul Wicking <paul.wicking@qt.io> | 2023-08-08 12:28:28 +0200 |
---|---|---|
committer | Paul Wicking <paul.wicking@qt.io> | 2023-08-08 13:41:38 +0200 |
commit | 23fd844bf85f1742751b960fd32e8da4e16fc793 (patch) | |
tree | 01baa41f3e1f393691e3e6921c9b7096906eda36 /tests/auto/qdoc/generatedoutput | |
parent | e6ba3da353e3a5e70023678c765d4f81aff58c42 (diff) |
Don't let CMD_VALUE break CMD_TABLE
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
Pick-to: 6.6 6.5
Change-Id: I06c9c25b4ff792621d56e5eb802178cfd376f8c3
Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io>
Diffstat (limited to 'tests/auto/qdoc/generatedoutput')
9 files changed, 246 insertions, 0 deletions
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 <TableAfterValue></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..99b8fe13a --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/tableaftervalue/tableaftervalue.xml @@ -0,0 +1,60 @@ +<?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: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 8b8a3d60e..2bd7dbc9f 100644 --- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp +++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp @@ -62,6 +62,7 @@ private slots: void proxyPage(); void nonAsciiCharacterInput(); void lineComments(); + void tableAfterValue(); private: QScopedPointer<QTemporaryDir> m_outputDir; @@ -313,6 +314,16 @@ void tst_generatedOutput::illformated_documentation() "brief-adventures.html"); } +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", |