Update QSyntaxHighlighter docs to use QRegularExpression

Update the QSyntaxHighlighter examples to use the new QRegularExpression
class in place of QRegExp.

Fix typos. Remove duplicated snippet. Replace lengthy section of
duplicate text in highlight(..) with a note to see the detailed
description.

Task-number: QTBUG-58494
Change-Id: Id8d94bddbed52e6e52feac107f6fc84e2fe4518a
Reviewed-by: Samuel Gaist <samuel.gaist@edeltech.ch>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>

2 files changed, 22 insertions, 60 deletions

diff --git a/src/gui/doc/snippets/code/src_gui_text_qsyntaxhighlighter.cpp b/src/gui/doc/snippets/code/src_gui_text_qsyntaxhighlighter.cpp
index da960088b7..bb27eb9612 100644
--- a/src/gui/doc/snippets/code/src_gui_text_qsyntaxhighlighter.cpp
+++ b/src/gui/doc/snippets/code/src_gui_text_qsyntaxhighlighter.cpp
@@ -60,14 +60,13 @@ void MyHighlighter::highlightBlock(const QString &text)
     QTextCharFormat myClassFormat;
     myClassFormat.setFontWeight(QFont::Bold);
     myClassFormat.setForeground(Qt::darkMagenta);
-    QString pattern = "\\bMy[A-Za-z]+\\b";
 
-    QRegExp expression(pattern);
-    int index = text.indexOf(expression);
-    while (index >= 0) {
-        int length = expression.matchedLength();
-        setFormat(index, length, myClassFormat);
-        index = text.indexOf(expression, index + length);
+    QRegularExpression expression("\\bMy[A-Za-z]+\\b");
+    QRegularExpressionMatchIterator i = expression.globalMatch(text);
+    while (i.hasNext())
+    {
+      QRegularExpressionMatch match = i.next();
+      setFormat(match.capturedStart(), match.capturedLength(), myClassFormat);
     }
 }
 //! [1]
@@ -77,8 +76,8 @@ void MyHighlighter::highlightBlock(const QString &text)
 QTextCharFormat multiLineCommentFormat;
 multiLineCommentFormat.setForeground(Qt::red);
 
-QRegExp startExpression("/\\*");
-QRegExp endExpression("\\*/");
+QRegularExpression startExpression("/\\*");
+QRegularExpression endExpression("\\*/");
 
 setCurrentBlockState(0);
 
@@ -87,14 +86,15 @@ if (previousBlockState() != 1)
     startIndex = text.indexOf(startExpression);
 
 while (startIndex >= 0) {
-   int endIndex = text.indexOf(endExpression, startIndex);
+   QRegularExpressionMatch endMatch;
+   int endIndex = text.indexOf(endExpression, startIndex, &endMatch);
    int commentLength;
    if (endIndex == -1) {
        setCurrentBlockState(1);
        commentLength = text.length() - startIndex;
    } else {
        commentLength = endIndex - startIndex
-                       + endExpression.matchedLength();
+                       + endMatch.capturedLength();
    }
    setFormat(startIndex, commentLength, multiLineCommentFormat);
    startIndex = text.indexOf(startExpression,
@@ -104,25 +104,6 @@ while (startIndex >= 0) {
 
 
 //! [3]
-void MyHighlighter::highlightBlock(const QString &text)
-{
-    QTextCharFormat myClassFormat;
-    myClassFormat.setFontWeight(QFont::Bold);
-    myClassFormat.setForeground(Qt::darkMagenta);
-    QString pattern = "\\bMy[A-Za-z]+\\b";
-
-    QRegExp expression(pattern);
-    int index = text.indexOf(expression);
-    while (index >= 0) {
-        int length = expression.matchedLength();
-        setFormat(index, length, myClassFormat);
-        index = text.indexOf(expression, index + length);
-     }
- }
-//! [3]
-
-
-//! [4]
 struct ParenthesisInfo
 {
     QChar char;
@@ -133,4 +114,4 @@ struct BlockData : public QTextBlockUserData
 {
     QVector<ParenthesisInfo> parentheses;
 };
-//! [4]
+//! [3]
diff --git a/src/gui/text/qsyntaxhighlighter.cpp b/src/gui/text/qsyntaxhighlighter.cpp
index d5541b0df1..8834afc80e 100644
--- a/src/gui/text/qsyntaxhighlighter.cpp
+++ b/src/gui/text/qsyntaxhighlighter.cpp
@@ -243,6 +243,8 @@ void QSyntaxHighlighterPrivate::reformatBlock(const QTextBlock &block)
 
     \snippet code/src_gui_text_qsyntaxhighlighter.cpp 1
 
+    \target QSyntaxHighlighter multiblock
+
     Some syntaxes can have constructs that span several text
     blocks. For example, a C++ syntax highlighter should be able to
     cope with \c{/}\c{*...*}\c{/} multiline comments. To deal with
@@ -267,12 +269,12 @@ void QSyntaxHighlighterPrivate::reformatBlock(const QTextBlock &block)
     \snippet code/src_gui_text_qsyntaxhighlighter.cpp 2
 
     In the example above, we first set the current block state to
-    0. Then, if the previous block ended within a comment, we higlight
+    0. Then, if the previous block ended within a comment, we highlight
     from the beginning of the current block (\c {startIndex =
     0}). Otherwise, we search for the given start expression. If the
     specified end expression cannot be found in the text block, we
     change the current block state by calling setCurrentBlockState(),
-    and make sure that the rest of the block is higlighted.
+    and make sure that the rest of the block is highlighted.
 
     In addition you can query the current formatting and user data
     using the format() and currentBlockUserData() functions
@@ -411,33 +413,12 @@ void QSyntaxHighlighter::rehighlightBlock(const QTextBlock &block)
     setFormat() as often as necessary to apply any font and color
     changes that you require. For example:
 
-    \snippet code/src_gui_text_qsyntaxhighlighter.cpp 3
-
-    Some syntaxes can have constructs that span several text
-    blocks. For example, a C++ syntax highlighter should be able to
-    cope with \c{/}\c{*...*}\c{/} multiline comments. To deal with
-    these cases it is necessary to know the end state of the previous
-    text block (e.g. "in comment").
-
-    Inside your highlightBlock() implementation you can query the end
-    state of the previous text block using the previousBlockState()
-    function. After parsing the block you can save the last state
-    using setCurrentBlockState().
-
-    The currentBlockState() and previousBlockState() functions return
-    an int value. If no state is set, the returned value is -1. You
-    can designate any other value to identify any given state using
-    the setCurrentBlockState() function. Once the state is set the
-    QTextBlock keeps that value until it is set set again or until the
-    corresponding paragraph of text gets deleted.
+    \snippet code/src_gui_text_qsyntaxhighlighter.cpp 1
 
-    For example, if you're writing a simple C++ syntax highlighter,
-    you might designate 1 to signify "in comment". For a text block
-    that ended in the middle of a comment you'd set 1 using
-    setCurrentBlockState, and for other paragraphs you'd set 0.
-    In your parsing code if the return value of previousBlockState()
-    is 1, you would highlight the text as a C++ comment until you
-    reached the closing \c{*}\c{/}.
+    See the \l{QSyntaxHighlighter multiblock}{Detailed Description} for
+    examples of using setCurrentBlockState(), currentBlockState()
+    and previousBlockState() to handle syntaxes with constructs that
+    span several text blocks
 
     \sa previousBlockState(), setFormat(), setCurrentBlockState()
 */
@@ -581,7 +562,7 @@ void QSyntaxHighlighter::setCurrentBlockState(int newState)
     and store their relative position and the actual QChar in a simple
     class derived from QTextBlockUserData:
 
-    \snippet code/src_gui_text_qsyntaxhighlighter.cpp 4
+    \snippet code/src_gui_text_qsyntaxhighlighter.cpp 3
 
     During cursor navigation in the associated editor, you can ask the
     current QTextBlock (retrieved using the QTextCursor::block()