QDoc: Respect line continuation characters

Since a refactoring (d7eeb6b0f78781cac8b87f4f18894aca6a467ae6), QDoc no
longer parses trailing backslashes immediately preceding a newline
character as line continuation character correctly, in that content in
the continued line is duplicated. This is due to the refactoring not
properly updating the position.

The refactoring caused another side effect, addressed in
d988115e061622e2c7728e83295727be9303a1c3. That change caused a new side
effect that may cause leading and trailing whitespace characters in a
continued line to end up verbatim in the continued line.

This change seeks to address these two problems in the following way:
- Ensure the main loop of the method updates the starting position
  for the line of text at the end of each iteration.
- If a trailing backslash has been encountered, return a simplified
  string. This ensures that sequences of internal whitespace is
  replaced by a single space character.
- Change a local variable name to better reflect what it represents.
- Update the documentation for the method to account for the behavior
  change.

The reintroduction of `simplified()` return values may possibly have
unintentional consequences. For example, it may impact parsing of
regular expressions, as seen as side-effect of the original
refactoring.

Fixes: QTBUG-118558
Change-Id: I5bbf51b1923a5e04f324c3f92aeb1cceff8aab7c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 951a9dab91e8982fd8e6b01bce9ff58e2028aa1b)
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

10 files changed, 264 insertions, 6 deletions

diff --git a/src/qdoc/qdoc/docparser.cpp b/src/qdoc/qdoc/docparser.cpp
index 94fc1f71b..632361b92 100644
--- a/src/qdoc/qdoc/docparser.cpp
+++ b/src/qdoc/qdoc/docparser.cpp
@@ -2312,8 +2312,13 @@ QString DocParser::getOptionalArgument()
     backslashes (`\`) as line continuation character. Trailing backslashes and
     any newline character that follow them are removed.
 
-    Returns a string as if it was one continuous line of text, stripped of
-    leading and trailing whitespace characters.
+    Returns a string as if it was one continuous line of text. If trailing
+    backslashes are removed, the method returns a "simplified" QString, which
+    means any sequence of internal whitespace is replaced with a single space.
+
+    Whitespace at the start and end is always removed from the returned string.
+
+    \sa QString::simplified(), QString::trimmed().
  */
 QString DocParser::getRestOfLine()
 {
@@ -2334,25 +2339,32 @@ QString DocParser::getRestOfLine()
     QString rest_of_line;
     skipSpacesOnLine();
     bool trailing_backslash{ false };
+    bool return_simplified_string{ false };
 
-    for (qsizetype start_of_line = m_position; m_position < m_inputLength; ++m_position) {
+    for (qsizetype start_position = m_position; m_position < m_inputLength; ++m_position) {
         trailing_backslash = lineHasTrailingBackslash(trailing_backslash);
 
         if (!rest_of_line.isEmpty())
             rest_of_line += QLatin1Char(' ');
-        rest_of_line += m_input.sliced(start_of_line, m_position - start_of_line);
+        rest_of_line += m_input.sliced(start_position, m_position - start_position);
 
-        if (trailing_backslash)
+        if (trailing_backslash) {
             rest_of_line.chop(1);
+            return_simplified_string = true;
+        }
 
         if (m_position < m_inputLength)
             ++m_position;
 
         if (!trailing_backslash)
             break;
+        start_position = m_position;
     }
 
-    return rest_of_line.simplified();
+    if (return_simplified_string)
+        return rest_of_line.simplified();
+
+    return rest_of_line.trimmed();
 }
 
 /*!
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct-members.html b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct-members.html
new file mode 100644
index 000000000..7fe474e80
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct-members.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- trailing_backslashes.cpp -->
+  <title>List of All Members for Struct | TrailingBackslashes</title>
+</head>
+<body>
+<li>Struct</li>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">List of All Members for Struct</h1>
+<p>This is the complete list of members for <a href="struct.html">Struct</a>, including inherited members.</p>
+<ul>
+<li class="fn" translate="no"><span class="name"><b><a href="struct.html#MultipleTrailingSlashes" translate="no">MultipleTrailingSlashes</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="struct.html#multipleTrailingSlashesAndRandomWhitespace" translate="no">multipleTrailingSlashesAndRandomWhitespace</a></b></span>()</li>
+<li class="fn" translate="no"><span class="name"><b><a href="struct.html#oneTrailingSlash" translate="no">oneTrailingSlash</a></b></span>()</li>
+</ul>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.html b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.html
new file mode 100644
index 000000000..0e5a0b45d
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.html
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- trailing_backslashes.cpp -->
+  <title>Struct Struct | TrailingBackslashes</title>
+</head>
+<body>
+<li>Struct</li>
+<div class="sidebar">
+<div class="toc">
+<h3 id="toc">Contents</h3>
+<ul>
+<li class="level1"><a href="#public-functions">Public Functions</a></li>
+<li class="level1"><a href="#details">Detailed Description</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title" translate="no">Struct Struct</h1>
+<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;Struct&gt;</span></td></tr>
+</table></div>
+<ul>
+<li><a href="struct-members.html">List of all members, including inherited members</a></li>
+</ul>
+<h2 id="public-functions">Public Functions</h2>
+<div class="table"><table class="alignedsummary" translate="no">
+<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="struct.html#MultipleTrailingSlashes" translate="no">MultipleTrailingSlashes</a></b>()</td></tr>
+<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="struct.html#multipleTrailingSlashesAndRandomWhitespace" translate="no">multipleTrailingSlashesAndRandomWhitespace</a></b>()</td></tr>
+<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="struct.html#oneTrailingSlash" translate="no">oneTrailingSlash</a></b>()</td></tr>
+</table></div>
+<!-- $$$Struct-description -->
+<div class="descr">
+<h2 id="details">Detailed Description</h2>
+</div>
+<!-- @@@Struct -->
+<div class="func">
+<h2>Member Function Documentation</h2>
+<!-- $$$MultipleTrailingSlashes[overload1]$$$MultipleTrailingSlashes -->
+<h3 class="fn" translate="no" id="MultipleTrailingSlashes"><span class="type">void</span> Struct::<span class="name">MultipleTrailingSlashes</span>()</h3>
+<p><b>See also </b><a href="struct.html#oneTrailingSlash" translate="no">one slash</a>.</p>
+<!-- @@@MultipleTrailingSlashes -->
+<!-- $$$multipleTrailingSlashesAndRandomWhitespace[overload1]$$$multipleTrailingSlashesAndRandomWhitespace -->
+<h3 class="fn" translate="no" id="multipleTrailingSlashesAndRandomWhitespace"><span class="type">void</span> Struct::<span class="name">multipleTrailingSlashesAndRandomWhitespace</span>()</h3>
+<p><b>See also </b><a href="struct.html#MultipleTrailingSlashes" translate="no">two slashes here</a>.</p>
+<!-- @@@multipleTrailingSlashesAndRandomWhitespace -->
+<!-- $$$oneTrailingSlash[overload1]$$$oneTrailingSlash -->
+<h3 class="fn" translate="no" id="oneTrailingSlash"><span class="type">void</span> Struct::<span class="name">oneTrailingSlash</span>()</h3>
+<p><b>See also </b><a href="struct.html#multipleTrailingSlashesAndRandomWhitespace" translate="no">two slashes again</a>.</p>
+<!-- @@@oneTrailingSlash -->
+</div>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.webxml b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.webxml
new file mode 100644
index 000000000..86f6fcd59
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.webxml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<WebXML>
+    <document>
+        <struct name="Struct" href="struct.html" status="active" access="public" location="trailing_backslashes.h" documented="true" module="TrailingBackslashes">
+            <description/>
+            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()">
+                <description>
+                    <see-also>
+                        <link raw="one slash" href="struct.html#oneTrailingSlash" type="function">one slash</link>
+                    </see-also>
+                </description>
+            </function>
+            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()">
+                <description>
+                    <see-also>
+                        <link raw="two slashes here" href="struct.html#MultipleTrailingSlashes" type="function">two slashes here</link>
+                    </see-also>
+                </description>
+            </function>
+            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()">
+                <description>
+                    <see-also>
+                        <link raw="two slashes again" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" type="function">two slashes again</link>
+                    </see-also>
+                </description>
+            </function>
+        </struct>
+    </document>
+</WebXML>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.xml b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.xml
new file mode 100644
index 000000000..48efdadb7
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.xml
@@ -0,0 +1,57 @@
+<?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></db:title>
+<db:productname>TrailingBackslashes</db:productname>
+<db:titleabbrev>TrailingBackslashes Reference Documentation</db:titleabbrev>
+<db:abstract>
+<db:para>TrailingBackslashes Reference Documentation.</db:para></db:abstract>
+</db:info>
+<db:variablelist>
+<db:varlistentry>
+<db:term>Header</db:term>
+<db:listitem>
+<db:para>Struct</db:para>
+</db:listitem>
+</db:varlistentry>
+</db:variablelist>
+<db:section xml:id="details">
+<db:title>Detailed Description</db:title>
+</db:section>
+<db:section xml:id="member-function-documentation">
+<db:title>Member Function Documentation</db:title>
+<db:section xml:id="MultipleTrailingSlashes">
+<db:title>void Struct::MultipleTrailingSlashes()</db:title>
+<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="struct.xml#oneTrailingSlash">one slash</db:link></db:member>
+</db:simplelist>
+</db:para>
+</db:section>
+</db:section>
+<db:section xml:id="multipleTrailingSlashesAndRandomWhitespace">
+<db:title>void Struct::multipleTrailingSlashesAndRandomWhitespace()</db:title>
+<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="struct.xml#MultipleTrailingSlashes">two slashes here</db:link></db:member>
+</db:simplelist>
+</db:para>
+</db:section>
+</db:section>
+<db:section xml:id="oneTrailingSlash">
+<db:title>void Struct::oneTrailingSlash()</db:title>
+<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="struct.xml#multipleTrailingSlashesAndRandomWhitespace">two slashes again</db:link></db:member>
+</db:simplelist>
+</db:para>
+</db:section>
+</db:section>
+</db:section>
+</db:article>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/trailingbackslashes.index b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/trailingbackslashes.index
new file mode 100644
index 000000000..f9e9c4ff0
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/trailingbackslashes.index
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE QDOCINDEX>
+<INDEX url="" title="TrailingBackslashes Reference Documentation" version="" project="TrailingBackslashes">
+    <namespace name="" status="active" access="public" module="trailingbackslashes">
+        <struct name="Struct" href="struct.html" status="active" access="public" location="trailing_backslashes.h" documented="true" module="TrailingBackslashes">
+            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()"/>
+            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()"/>
+            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()"/>
+        </struct>
+        <module name="TrailingBackslashes" href="trailingbackslashes-module.html" status="internal" seen="false" title=""/>
+    </namespace>
+</INDEX>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.cpp b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.cpp
new file mode 100644
index 000000000..f2728c5f5
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.cpp
@@ -0,0 +1,32 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \struct Struct
+*/
+
+/*!
+    \fn void Struct::oneTrailingSlash()
+    \keyword one \
+    slash
+
+    \sa {two slashes again}
+*/
+
+/*!
+    \fn void Struct::MultipleTrailingSlashes()
+    \keyword two \
+             slashes \
+             here
+
+    \sa {one slash}
+*/
+
+/*!
+    \fn void Struct::multipleTrailingSlashesAndRandomWhitespace()
+    \keyword   two\
+    slashes \
+    again
+
+    \sa {two slashes here}
+*/
diff --git a/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.h b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.h
new file mode 100644
index 000000000..b1d61528e
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.h
@@ -0,0 +1,14 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+#ifndef TRAILING_BACKSLASHES_H
+#define TRAILING_BACKSLASHES_H
+
+struct Struct
+{
+    void oneTrailingSlash(){};
+    void MultipleTrailingSlashes(){};
+    void multipleTrailingSlashesAndRandomWhitespace(){};
+};
+
+#endif // TRAILING_BACKSLASHES_H
diff --git a/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailingbackslashes.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailingbackslashes.qdocconf
new file mode 100644
index 000000000..ac8478015
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailingbackslashes.qdocconf
@@ -0,0 +1,19 @@
+include(../configs/config.qdocconf)
+project = TrailingBackslashes
+
+headerdirs  = .
+sourcedirs  = .
+exampledirs = .
+
+outputformats             = WebXML HTML DocBook
+WebXML.quotinginformation = true
+WebXML.nosubdirs          = true
+WebXML.outputsubdir = trailingbackslashes
+
+HTML.nosubdirs = true
+HTML.outputsubdir = trailingbackslashes
+
+DocBook.nosubdirs = true
+DocBook.outputsubdir = trailingbackslashes
+
+warninglimit = 1
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 1429ac988..5a61ad1de 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -63,6 +63,7 @@ private slots:
     void nonAsciiCharacterInput();
     void lineComments();
     void tableAfterValue();
+    void trailingBackslashes();
     void modulestateCommand();
 
 private:
@@ -640,6 +641,16 @@ void tst_generatedOutput::lineComments()
     );
 }
 
+void tst_generatedOutput::trailingBackslashes()
+{
+    testAndCompare("testdata/trailing_backslashes/trailingbackslashes.qdocconf",
+                   "trailingbackslashes/struct-members.html "
+                   "trailingbackslashes/struct.html "
+                   "trailingbackslashes/struct.webxml "
+                   "trailingbackslashes/struct.xml "
+                   "trailingbackslashes/trailingbackslashes.index");
+}
+
 void tst_generatedOutput::modulestateCommand()
 {
     testAndCompare("testdata/modulestate/modulestate.qdocconf",