From 2200d92506e17fa85f23c639b78e19421f7696be Mon Sep 17 00:00:00 2001 From: Paul Wicking Date: Thu, 26 Oct 2023 08:36:14 +0200 Subject: QDoc: Respect line continuation characters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ö (cherry picked from commit 951a9dab91e8982fd8e6b01bce9ff58e2028aa1b) Reviewed-by: Paul Wicking --- src/qdoc/qdoc/docparser.cpp | 24 ++++++--- .../trailingbackslashes/struct-members.html | 19 ++++++++ .../trailingbackslashes/struct.html | 53 ++++++++++++++++++++ .../trailingbackslashes/struct.webxml | 29 +++++++++++ .../expected_output/trailingbackslashes/struct.xml | 57 ++++++++++++++++++++++ .../trailingbackslashes/trailingbackslashes.index | 12 +++++ .../trailing_backslashes/trailing_backslashes.cpp | 32 ++++++++++++ .../trailing_backslashes/trailing_backslashes.h | 14 ++++++ .../trailingbackslashes.qdocconf | 19 ++++++++ .../qdoc/generatedoutput/tst_generatedoutput.cpp | 11 +++++ 10 files changed, 264 insertions(+), 6 deletions(-) create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct-members.html create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.html create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.webxml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/struct.xml create mode 100644 tests/auto/qdoc/generatedoutput/expected_output/trailingbackslashes/trailingbackslashes.index create mode 100644 tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.cpp create mode 100644 tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailing_backslashes.h create mode 100644 tests/auto/qdoc/generatedoutput/testdata/trailing_backslashes/trailingbackslashes.qdocconf 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 @@ + + + + + + List of All Members for Struct | TrailingBackslashes + + +
  • Struct
    • +
    +

    List of All Members for Struct

    +

    This is the complete list of members for Struct, including inherited members.

    + + + 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 @@ + + + + + + Struct Struct | TrailingBackslashes + + +
  • Struct
    • +
    +
    +

    Contents

    + +
    +
    +

    Struct Struct

    +
    + +
    Header: #include <Struct>
    + +

    Public Functions

    +
    + + + +
    void MultipleTrailingSlashes()
    void multipleTrailingSlashesAndRandomWhitespace()
    void oneTrailingSlash()
    + +
    +

    Detailed Description

    +
    + +
    +

    Member Function Documentation

    + +

    void Struct::MultipleTrailingSlashes()

    +

    See also one slash.

    + + +

    void Struct::multipleTrailingSlashesAndRandomWhitespace()

    +

    See also two slashes here.

    + + +

    void Struct::oneTrailingSlash()

    +

    See also two slashes again.

    + +
    + + 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 @@ + + + + + + + + + one slash + + + + + + + two slashes here + + + + + + + two slashes again + + + + + + 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 @@ + + + + +TrailingBackslashes +TrailingBackslashes Reference Documentation + +TrailingBackslashes Reference Documentation. + + + +Header + +Struct + + + + +Detailed Description + + +Member Function Documentation + +void Struct::MultipleTrailingSlashes() + +See Also +See also + +one slash + + + + + +void Struct::multipleTrailingSlashesAndRandomWhitespace() + +See Also +See also + +two slashes here + + + + + +void Struct::oneTrailingSlash() + +See Also +See also + +two slashes again + + + + + + 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 @@ + + + + + + + + + + + + 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", -- cgit v1.2.3