diff options
Diffstat (limited to 'src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation')
20 files changed, 421 insertions, 0 deletions
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/another-page-with-comments-in-the-brief.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/another-page-with-comments-in-the-brief.html new file mode 100644 index 000000000..71ef2af25 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/another-page-with-comments-in-the-brief.html @@ -0,0 +1,18 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- brief_adventures.qdoc --> + <meta name="description" content="Another test that the \brief command isn't completely borked"> + <title>There's no end to the possibilities! | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">There's no end to the possibilities!</h1> +<!-- $$$another-page-with-comments-in-the-brief-description --> +<div class="descr" id="details"> +<p>The brief for this page is: "Another test that the \brief command isn't completely borked". Notice the lack of a trailing full stop in the brief. QDoc should generate a warning about that when generating HTML.</p> +</div> +<!-- @@@another-page-with-comments-in-the-brief --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/brief-adventures.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/brief-adventures.html new file mode 100644 index 000000000..1600b124c --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/brief-adventures.html @@ -0,0 +1,27 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- brief_adventures.qdoc --> + <meta name="description" content="Test that the \brief command doesn't eat content that follows it."> + <title>Adventures with QDoc's \brief command | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"> +<div class="toc"> +<h3 id="toc">Contents</h3> +<ul> +<li class="level1"><a href="#further-details">Further details</a></li> +</ul> +</div> +<div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">Adventures with QDoc's \brief command</h1> +<!-- $$$brief-adventures.html-description --> +<div class="descr" id="details"> +<p>The purpose of this test data is to provide a regression mechanism as part of QDoc's end-to-end test, tst_generatedOutput, for an issue (QTBUG-70959) that was reported against QDoc's \keyword command. The issue, as experienced by the reporter of the bug, is that if the \keyword command isn't followed by a new command, or is the last command in a paragraph, the following paragraph is "eaten". That means the entire paragraph is understood by QDoc as keywords and included as html meta information instead of as part of the rendered output.</p> +<h2 id="further-details">Further details</h2> +<p>The bug report is at <a href="https://bugreports.qt.io/browse/QTBUG-70959">https://bugreports.qt.io/browse/QTBUG-70959</a>. It refers to a change that bypassed the issue by moving the \keyword command, at <a href="https://codereview.qt-project.org/c/qt/qtdoc/+/242033/">https://codereview.qt-project.org/c/qt/qtdoc/+/242033/</a>.</p> +</div> +<!-- @@@brief-adventures.html --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatted-examples.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatted-examples.html new file mode 100644 index 000000000..5253ae1d1 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatted-examples.html @@ -0,0 +1,31 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- illformatted-examples.qdoc --> + <meta name="description" content="Demonstrate correctness for example generation."> + <title>Test generated output for illformatted examples | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"> +<div class="toc"> +<h3 id="toc">Contents</h3> +<ul> +<li class="level1"><a href="#qml-examples">QML Examples</a></li> +<li class="level1"><a href="#c-examples">C++ Examples</a></li> +</ul> +</div> +<div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">Test generated output for illformatted examples</h1> +<!-- $$$illformatted-examples.html-description --> +<div class="descr" id="details"> +<p>This test includes the following examples:</p> +<h2 id="qml-examples">QML Examples</h2> +<div class="table"><table class="annotated"> +<tr class="odd topAlign"><td class="tblName" translate="no"><p><a href="illformatteddocumentation-someexample-example.html">QDoc: some example</a></p></td><td class="tblDescr"><p></p></td></tr> +</table></div> +<h2 id="c-examples">C++ Examples</h2> +</div> +<!-- @@@illformatted-examples.html --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation-someexample-example.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation-someexample-example.html new file mode 100644 index 000000000..ebeb5a5b4 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation-someexample-example.html @@ -0,0 +1,16 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- some_example.qdoc --> + <title>QDoc: some example | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">QDoc: some example</h1> +<!-- $$$someexample-description --> +<div class="descr" id="details"> +</div> +<!-- @@@someexample --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation.index b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation.index new file mode 100644 index 000000000..e9898cd2e --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/illformatteddocumentation.index @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE QDOCINDEX> +<INDEX url="" title="IllformattedDocumentation Reference Documentation" version="" project="IllformattedDocumentation"> + <namespace name="" status="active" access="public" module="illformatteddocumentation"> + <page name="brief-adventures.html" href="brief-adventures.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Adventures with QDoc's \brief command" fulltitle="Adventures with QDoc's \brief command" subtitle="" brief="Test that the \brief command doesn't eat content that follows it"> + <keyword name="some-keyword" title="some_keyword"/> + <contents name="further-details" title="Further details" level="1"/> + </page> + <page name="someexample" href="illformatteddocumentation-someexample-example.html" status="active" location="some_example.qdoc" documented="true" groups="illformatted-examples-qml" subtype="example" title="QDoc: some example" fulltitle="QDoc: some example" subtitle=""/> + <page name="illformatted-examples.html" href="illformatted-examples.html" status="active" location="illformatted-examples.qdoc" documented="true" groups="all-examples" subtype="page" title="Test generated output for illformatted examples" fulltitle="Test generated output for illformatted examples" subtitle="" brief="Demonstrate correctness for example generation"> + <contents name="qml-examples" title="QML Examples" level="1"/> + <contents name="c-examples" title="C++ Examples" level="1"/> + </page> + <page name="another-page-with-comments-in-the-brief" href="another-page-with-comments-in-the-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="There's no end to the possibilities!" fulltitle="There's no end to the possibilities!" subtitle="" brief="Another test that the \brief command isn't completely borked"/> + <page name="page-with-an-image-at-the-top.html" href="page-with-an-image-at-the-top.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="This page starts with an image" fulltitle="This page starts with an image" subtitle="" brief="This page has an image right at the top"/> + <page name="page-with-comment-after-brief.html" href="page-with-comment-after-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet another adventure with QDoc's \brief command" fulltitle="Yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command doesn't eat content that follows it"/> + <page name="page-with-comment-in-brief.html" href="page-with-comment-in-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet, yet another adventure with QDoc's \brief command" fulltitle="Yet, yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command isn't entirely broken"/> + <group name="all-examples" href="all-examples.html" status="internal" seen="false" title=""/> + <group name="illformatted-examples-qml" href="illformatted-examples-qml.html" status="internal" seen="false" title=""/> + <module name="sometestgroup" href="sometestgroup-module.html" status="internal" seen="false" title=""/> + </namespace> +</INDEX> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-an-image-at-the-top.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-an-image-at-the-top.html new file mode 100644 index 000000000..e66e6ba51 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-an-image-at-the-top.html @@ -0,0 +1,19 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- brief_adventures.qdoc --> + <meta name="description" content="This page has an image right at the top."> + <title>This page starts with an image | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">This page starts with an image</h1> +<!-- $$$page-with-an-image-at-the-top.html-description --> +<div class="descr" id="details"> +<p class="centerAlign"><font color="red">[Missing image leonardo-da-vinci.png]</font></p><p>The image should render as expected, and the alternate text should be there, too. This text is contained in its own paragraph following the image.</p> +<p>This paragraph is a new paragraph, and doesn't contain an image.</p> +</div> +<!-- @@@page-with-an-image-at-the-top.html --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-after-brief.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-after-brief.html new file mode 100644 index 000000000..fc6fa1b92 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-after-brief.html @@ -0,0 +1,18 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- brief_adventures.qdoc --> + <meta name="description" content="Another test that the \brief command doesn't eat content that follows it."> + <title>Yet another adventure with QDoc's \brief command | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">Yet another adventure with QDoc's \brief command</h1> +<!-- $$$page-with-comment-after-brief.html-description --> +<div class="descr" id="details"> +<p>This paragraph should render normally, but might be eaten by the \brief brief because the brief is followed by a QDoc comment (which shouldn't be rendered at all).</p> +</div> +<!-- @@@page-with-comment-after-brief.html --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-in-brief.html b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-in-brief.html new file mode 100644 index 000000000..4283ae544 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/html/page-with-comment-in-brief.html @@ -0,0 +1,18 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> +<!-- brief_adventures.qdoc --> + <meta name="description" content="Another test that the \brief command isn't entirely broken."> + <title>Yet, yet another adventure with QDoc's \brief command | IllformattedDocumentation</title> +</head> +<body> +<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">Yet, yet another adventure with QDoc's \brief command</h1> +<!-- $$$page-with-comment-in-brief.html-description --> +<div class="descr" id="details"> +<p>The brief for this page is: "Another test that the \brief command isn't entirely broken."</p> +</div> +<!-- @@@page-with-comment-in-brief.html --> +</body> +</html> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/another-page-with-comments-in-the-brief.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/another-page-with-comments-in-the-brief.webxml new file mode 100644 index 000000000..7e82dfad6 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/another-page-with-comments-in-the-brief.webxml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="another-page-with-comments-in-the-brief" href="another-page-with-comments-in-the-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="There's no end to the possibilities!" fulltitle="There's no end to the possibilities!" subtitle="" brief="Another test that the \brief command isn't completely borked"> + <description> + <brief>Another test that the \brief command isn't completely borked</brief> + <para>The brief for this page is: "Another test that the \brief command isn't completely borked". Notice the lack of a trailing full stop in the brief. QDoc should generate a warning about that when generating HTML.</para> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/brief-adventures.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/brief-adventures.webxml new file mode 100644 index 000000000..3a6f5f2d5 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/brief-adventures.webxml @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="brief-adventures.html" href="brief-adventures.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Adventures with QDoc's \brief command" fulltitle="Adventures with QDoc's \brief command" subtitle="" brief="Test that the \brief command doesn't eat content that follows it"> + <keyword name="some-keyword" title="some_keyword"/> + <contents name="further-details" title="Further details" level="1"/> + <description> + <brief>Test that the \brief command doesn't eat content that follows it.</brief> + <para>The purpose of this test data is to provide a regression mechanism as part of QDoc's end-to-end test, tst_generatedOutput, for an issue (QTBUG-70959) that was reported against QDoc's \keyword command. The issue, as experienced by the reporter of the bug, is that if the \keyword command isn't followed by a new command, or is the last command in a paragraph, the following paragraph is "eaten". That means the entire paragraph is understood by QDoc as keywords and included as html meta information instead of as part of the rendered output.</para> + <section id="further-details"> + <heading level="1">Further details</heading> + <para>The bug report is at <link raw="https://bugreports.qt.io/browse/QTBUG-70959" href="https://bugreports.qt.io/browse/QTBUG-70959" type="external">https://bugreports.qt.io/browse/QTBUG-70959</link>. It refers to a change that bypassed the issue by moving the \keyword command, at <link raw="https://codereview.qt-project.org/c/qt/qtdoc/+/242033/" href="https://codereview.qt-project.org/c/qt/qtdoc/+/242033/" type="external">https://codereview.qt-project.org/c/qt/qtdoc/+/242033/</link>.</para> + </section> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatted-examples.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatted-examples.webxml new file mode 100644 index 000000000..b49d1b297 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatted-examples.webxml @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="illformatted-examples.html" href="illformatted-examples.html" status="active" location="illformatted-examples.qdoc" documented="true" groups="all-examples" subtype="page" title="Test generated output for illformatted examples" fulltitle="Test generated output for illformatted examples" subtitle="" brief="Demonstrate correctness for example generation"> + <contents name="qml-examples" title="QML Examples" level="1"/> + <contents name="c-examples" title="C++ Examples" level="1"/> + <description> + <brief>Demonstrate correctness for example generation.</brief> + <para>This test includes the following examples:</para> + <section id="qml-examples"> + <heading level="1">QML Examples</heading> + <table width="100%"> + <row> + <item> + <para> + <link raw="QDoc: some example" href="illformatteddocumentation-someexample-example.html" type="page" page="QDoc: some example"/> + </para> + </item> + <item> + <para></para> + </item> + </row> + </table> + </section> + <section id="c-examples"> + <heading level="1">C++ Examples</heading> + </section> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation-someexample-example.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation-someexample-example.webxml new file mode 100644 index 000000000..675e3d74f --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation-someexample-example.webxml @@ -0,0 +1,8 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="someexample" href="illformatteddocumentation-someexample-example.html" status="active" location="some_example.qdoc" documented="true" groups="illformatted-examples-qml" subtype="example" title="QDoc: some example" fulltitle="QDoc: some example" subtitle=""> + <description/> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation.index b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation.index new file mode 100644 index 000000000..e9898cd2e --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/illformatteddocumentation.index @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE QDOCINDEX> +<INDEX url="" title="IllformattedDocumentation Reference Documentation" version="" project="IllformattedDocumentation"> + <namespace name="" status="active" access="public" module="illformatteddocumentation"> + <page name="brief-adventures.html" href="brief-adventures.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Adventures with QDoc's \brief command" fulltitle="Adventures with QDoc's \brief command" subtitle="" brief="Test that the \brief command doesn't eat content that follows it"> + <keyword name="some-keyword" title="some_keyword"/> + <contents name="further-details" title="Further details" level="1"/> + </page> + <page name="someexample" href="illformatteddocumentation-someexample-example.html" status="active" location="some_example.qdoc" documented="true" groups="illformatted-examples-qml" subtype="example" title="QDoc: some example" fulltitle="QDoc: some example" subtitle=""/> + <page name="illformatted-examples.html" href="illformatted-examples.html" status="active" location="illformatted-examples.qdoc" documented="true" groups="all-examples" subtype="page" title="Test generated output for illformatted examples" fulltitle="Test generated output for illformatted examples" subtitle="" brief="Demonstrate correctness for example generation"> + <contents name="qml-examples" title="QML Examples" level="1"/> + <contents name="c-examples" title="C++ Examples" level="1"/> + </page> + <page name="another-page-with-comments-in-the-brief" href="another-page-with-comments-in-the-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="There's no end to the possibilities!" fulltitle="There's no end to the possibilities!" subtitle="" brief="Another test that the \brief command isn't completely borked"/> + <page name="page-with-an-image-at-the-top.html" href="page-with-an-image-at-the-top.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="This page starts with an image" fulltitle="This page starts with an image" subtitle="" brief="This page has an image right at the top"/> + <page name="page-with-comment-after-brief.html" href="page-with-comment-after-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet another adventure with QDoc's \brief command" fulltitle="Yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command doesn't eat content that follows it"/> + <page name="page-with-comment-in-brief.html" href="page-with-comment-in-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet, yet another adventure with QDoc's \brief command" fulltitle="Yet, yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command isn't entirely broken"/> + <group name="all-examples" href="all-examples.html" status="internal" seen="false" title=""/> + <group name="illformatted-examples-qml" href="illformatted-examples-qml.html" status="internal" seen="false" title=""/> + <module name="sometestgroup" href="sometestgroup-module.html" status="internal" seen="false" title=""/> + </namespace> +</INDEX> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-an-image-at-the-top.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-an-image-at-the-top.webxml new file mode 100644 index 000000000..da7b4f1d9 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-an-image-at-the-top.webxml @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="page-with-an-image-at-the-top.html" href="page-with-an-image-at-the-top.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="This page starts with an image" fulltitle="This page starts with an image" subtitle="" brief="This page has an image right at the top"> + <description> + <brief>This page has an image right at the top.</brief> + <para>The image should render as expected, and the alternate text should be there, too. This text is contained in its own paragraph following the image.</para> + <para>This paragraph is a new paragraph, and doesn't contain an image.</para> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-after-brief.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-after-brief.webxml new file mode 100644 index 000000000..f5b28e302 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-after-brief.webxml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="page-with-comment-after-brief.html" href="page-with-comment-after-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet another adventure with QDoc's \brief command" fulltitle="Yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command doesn't eat content that follows it"> + <description> + <brief>Another test that the \brief command doesn't eat content that follows it.</brief> + <para>This paragraph should render normally, but might be eaten by the \brief brief because the brief is followed by a QDoc comment (which shouldn't be rendered at all).</para> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-in-brief.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-in-brief.webxml new file mode 100644 index 000000000..575cd111d --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/expected/webxml/page-with-comment-in-brief.webxml @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<WebXML> + <document> + <page name="page-with-comment-in-brief.html" href="page-with-comment-in-brief.html" status="active" location="brief_adventures.qdoc" documented="true" subtype="page" title="Yet, yet another adventure with QDoc's \brief command" fulltitle="Yet, yet another adventure with QDoc's \brief command" subtitle="" brief="Another test that the \brief command isn't entirely broken"> + <description> + <brief>Another test that the \brief command isn't entirely broken.</brief> + <para>The brief for this page is: "Another test that the \brief command isn't entirely broken."</para> + </description> + </page> + </document> +</WebXML> diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/illformatted_documentation.qdocconf b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/illformatted_documentation.qdocconf new file mode 100644 index 000000000..716882f41 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/illformatted_documentation.qdocconf @@ -0,0 +1,29 @@ +project = IllformattedDocumentation + +headerdirs = ./src +sourcedirs = ./src +exampledirs = ./src + +outputformats = WebXML HTML +WebXML.quotinginformation = true +WebXML.nosubdirs = true +WebXML.outputsubdir = webxml + +warninglimit = 3 # The broken example generates three warnings + +sources.fileextensions = "*.qml *.cpp *.qdoc" +headers.fileextensions = "*.h" + +# images +imagedirs = ./src/images + +warninglimit.enabled = true + +# don't write host system-specific paths to index files +locationinfo = false + +# By default, use -outputdir directly, no subdir. +# outputsubdir '.' matches the root of expected_output/ +HTML.nosubdirs = true +HTML.outputsubdir = html + diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/brief_adventures.qdoc b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/brief_adventures.qdoc new file mode 100644 index 000000000..9bad0106b --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/brief_adventures.qdoc @@ -0,0 +1,75 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page brief-adventures.html + \title Adventures with QDoc's \\brief command + \brief Test that the \\brief command doesn't eat content that follows it. + \inmodule sometestgroup + \keyword some_keyword + + The purpose of this test data is to provide a regression mechanism as part + of QDoc's end-to-end test, tst_generatedOutput, for an issue (QTBUG-70959) + that was reported against QDoc's \\keyword command. The issue, as + experienced by the reporter of the bug, is that if the \\keyword command + isn't followed by a new command, or is the last command in a paragraph, + the following paragraph is "eaten". That means the entire paragraph is + understood by QDoc as keywords and included as html meta information + instead of as part of the rendered output. + + \section1 Further details + The bug report is at \l https://bugreports.qt.io/browse/QTBUG-70959. + It refers to a change that bypassed the issue by moving the \\keyword + command, at \l https://codereview.qt-project.org/c/qt/qtdoc/+/242033/. +*/ + +/*! + \page page-with-an-image-at-the-top.html + \title This page starts with an image + \brief This page has an image right at the top. + \image leonardo-da-vinci.png This is the alternate text for the image + The image should render as expected, and the alternate text should be + there, too. This text is contained in its own paragraph following the + image. + + This paragraph is a new paragraph, and doesn't contain an image. +*/ + +/*! + \page page-with-comment-after-brief.html + \title Yet another adventure with QDoc's \\brief command + \brief Another test that the \\brief command doesn't eat content that follows it. + //! This QDoc comment might cause an issue, let's try it! + + This paragraph should render normally, but might be eaten by the \\brief + brief because the brief is followed by a QDoc comment (which shouldn't be + rendered at all). +*/ + +/*! + \page page-with-comment-in-brief.html + \title Yet, yet another adventure with QDoc's \\brief command + \brief Another test that the \\brief command //! Brief continues below + isn't entirely broken. + + The brief for this page is: + "Another test that the \\brief command isn't entirely broken." +*/ + +/*! + \page another-page-with-comments-in-the-brief + \title There's no end to the possibilities! + \brief Another test that the \\brief command //! Doesn't contain a full stop. + //! QDoc's CMD_BRIEF should issue a warning when it doesn't end with a full + //! stop. However, if a \\brief is followed by a line comment (i.e. `//!`), + //! the warning isn't issued. This is tied to how `CMD_BRIEF` performs + //! macro expansion and command processing; in the case of line comments in + //! the argument, the last character of the brief's atom isn't a full stop. + isn't completely borked + + The brief for this page is: + "Another test that the \\brief command isn't completely borked". Notice the + lack of a trailing full stop in the brief. QDoc should generate a warning + about that when generating HTML. + +*/ diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/illformatted-examples.qdoc b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/illformatted-examples.qdoc new file mode 100644 index 000000000..5bfa9e7f6 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/illformatted-examples.qdoc @@ -0,0 +1,17 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page illformatted-examples.html + \ingroup all-examples + \title Test generated output for illformatted examples + \brief Demonstrate correctness for example generation. + + This test includes the following examples: + + \section1 QML Examples + \annotatedlist illformatted-examples-qml + + \section1 C++ Examples + \annotatedlist illformatted-examples-cpp +*/ diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/some_example.qdoc b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/some_example.qdoc new file mode 100644 index 000000000..a64605b87 --- /dev/null +++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/illformatted_documentation/src/some_example.qdoc @@ -0,0 +1,8 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example someexample + \title QDoc: some example + \ingroup illformatted-examples-qml +*/ |