QDoc: Protect CMD_BRIEF from calls to getRestOfLine()

QDoc's \brief command takes an entire paragraph as its argument, and
allows for the processing QDoc commands or macros that appear in the
argument. Due to QDoc's internals, such commands may consume newline
characters that the \brief command relies upon as its end condition.
Thus the \brief command may erroneously include the following content
as part of its argument.

A previous patch addressed this issue specifically for `CMD_KEYWORD`.
However, there are still multiple possible pathways in QDoc's code
where the bug may be triggered. This patch seeks to add guards against
this (mis)behavior in the following ways:

Modify the `scopedenum` output test by adding a `\brief` to it, as that
already makes use of `CMD_SINCELIST`. This modification exposes that
the bug is also triggered in this case. To guard against the behavior,
add a call to `leavePara()` in the parsing of `CMD_SINCELIST`. This
resolves the issue, with no visual impact when generating the
documentation for Qt.

In parsing `CMD_IMAGE`, there's a call to `getRestOfLine()` when
parsing the alternate text for an image. This patch adds test data for
a page that features an image with an alternate text right at the top.
This doesn't trigger the bug. The test data is kept as part of this
patch as proof that the bug does not occur in this case, and to guard
against possible future regressions.

In parsing `CMD_OMITVALUE`, there's a call to getRestOfLine() while
skipping potential description paragraphs. Modify the `scopedenum`
test by adding a `\brief` to the `TestQDoc::Test::ScopedEnum` enum
documentation, and rearrange the valuelist such that an `\omitvalue`
command immediately follows the `\brief`. This triggers the bug. Add a
call to `leavePara()` upon entering the case. This resolves the issue,
with no visual impact when generating the documentation for Qt.

In parsing of QDoc's line comments, `//!`, there's a call to
`getRestOfLine()` while also adjusting the position. While adding a
call to `leavePara()` in the parsing of line comments modifies the
output of QDoc in what is arguably a correct way (that is, paragraphs
are inserted where new paragraphs should be reasonably expected), that
modification causes an unwanted side-effect in `CMD_BRIEF`:
the consumption of the newline character by `getRestIfLine()` breaks
`CMD_BRIEF` if one inserts a line comment within the arguments to the
command and continue the argument on the following line. For example:

    \brief SANTA //! wait for it...
           MOZZARELLA!

will, surprisingly, make the brief contain only SANTA, not SANTA
MOZZARELLA! as one would expect.

As the proposed workaround of inserting calls to `leavePara()` is found
to have unwanted side-effects on `CMD_BRIEF` in the case of QDoc line
comments, resolving this is left for a future change.

Task-number: QTBUG-113118
Change-Id: Ic71e7e15c62a9beb834690f24f7538500346cb60
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 1 insertions, 0 deletions

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/illformatteddocumentation.index b/tests/auto/qdoc/generatedoutput/expected_output/html/illformatteddocumentation.index
index 8acd9baa2..96db721b1 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/illformatteddocumentation.index
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/illformatteddocumentation.index
@@ -11,6 +11,7 @@
             <contents name="qml-examples" title="QML Examples" level="1"/>
             <contents name="c-examples" title="C++ Examples" level="1"/>
         </page>
+        <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"/>
         <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=""/>