diff options
| author | Paul Wicking <paul.wicking@qt.io> | 2023-04-14 21:24:36 +0200 |
|---|---|---|
| committer | Paul Wicking <paul.wicking@qt.io> | 2023-04-25 10:02:54 +0200 |
| commit | aa24730660aec04871ac72b8c829b8e50909e47c (patch) | |
| tree | bec47758e9cfb20359653144dddfd530a74e769a /tests/auto/qdoc/generatedoutput/expected_output/brief-adventures.html | |
| parent | 3465735012de9dda79b31b4452663878987d4aa9 (diff) | |
| download | qttools-aa24730660aec04871ac72b8c829b8e50909e47c.tar.gz | |
QDoc: Make \keyword enforce paragraphs
QDoc's \brief command takes an entire paragraph as its argument, and
also allows for the processing QDoc commands or macros that appear in
the argument. Due to QDoc's internals, this may lead to a situation
where such commands consume newline characters that the \brief command
relies upon as indicator of its end condition, leading to a situation
where the \brief command erroneously includes the following paragraph
as part of its argument.
In particular, this may cause issues for certain commands that
"naturally" fit in a document "header". For example, given the
following content in a .qdoc file:
/*!
\page the_page.html
\title The title
\brief This is the brief.
\keyword the_keyword
Lorem ipsum dolor sit amet.
Santa Mozzarella!
*/
the brief will contain:
This is the brief. Lorem ipsum dolor sit amet.
And the only content in the generated output will, unexpectedly, be
Santa Mozzarella!
Due to its design, modifications to the \brief command are difficult,
as they will inevitably change QDoc's behavior significantly, with the
possibility of silent breakage. Therefore, enforce that the \keyword
command starts ends the paragraph it occurs in before further
processing.
This change includes a reproducing test case for the behavior in
question, which serves to validate the fix as well as as a guard for
future regressions.
Fixes: QTBUG-70959
Change-Id: I8f5b8a4aebf2ed2040bf43c1d4551ec280fc895a
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Diffstat (limited to 'tests/auto/qdoc/generatedoutput/expected_output/brief-adventures.html')
| -rw-r--r-- | tests/auto/qdoc/generatedoutput/expected_output/brief-adventures.html | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/brief-adventures.html b/tests/auto/qdoc/generatedoutput/expected_output/brief-adventures.html new file mode 100644 index 000000000..009104a6f --- /dev/null +++ b/tests/auto/qdoc/generatedoutput/expected_output/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" translate="no">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/" translate="no">https://codereview.qt-project.org/c/qt/qtdoc/+/242033/</a>.</p> +</div> +<!-- @@@brief-adventures.html --> +</body> +</html> |