Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-89702

Improve the QRegExp->QRegularExpression docs

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Reported
    • Priority: P2: Important
    • Resolution: Unresolved
    • Affects Version/s: 6.0.0
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      Duplication

      The docs for porting from QRegExp to QRegularExpression are duplicated:

      https://doc.qt.io/qt-6/qregexp.html#porting-to-qregularexpression
      https://doc.qt.io/qt-6/qtcore-changes-qt6.html#regular-expression-classes

      The first one is a straight up "move" of the Qt5 docs from QRegularExpression to QRegExp. The second one is something slightly different – some parts have been copied and pasted from QRegularExpression/QRegExp, some parts added, some other parts "adapted".

      (For some reason, the parts that have been copied and pasted have not been done from the actual sources – they seem to have been copied and pasted from the rendered HTML docs of QRegExp, then had formatting re-applied. You can clearly tell that some formatting bits got lost in the way.)

      These docs should obviously be centralized. STRONG suggestion: move the docs from QRegExp sources and overwrite the relevant parts of the Qt porting guide.

      Missing links

      Wherever the docs end up, they should be linked from the "other two" places. E.g. if they get centralized in the Qt 6 porting guide, then they should be linked from QRegExp and from QRegularExpression docs.

      Typos

      https://doc.qt.io/qt-6/qtcore-changes-qt6.html#regular-expression-classes

      The Qt 6 porting guide has a number of errors (not including the typographical problems due to c&p, see above).

      1. QRegExp occurrences are randonly prefixed by a \c command which makes it monospaced, rather than making qdoc generate links to it automatically, as it should be.
      2. "In Qt6, all methods taking the QRegExp got removed from our code-base."
        1. we don't use "our" (who's the "we" talking?) in the documentation, we use "Qt".
        2. It's "codebase" or "code base".
      3. "QRegularExpression implements Perl-compatible regular expressions. It fully supports Unicode. For an overview of the regular expression syntax supported by QRegularExpression, please refer to the aforementioned pcrepattern(3) man page. A regular expression is made up of two things: a pattern string and a set of pattern options that change the meaning of the pattern string."
        • This got lifted from QRegularExpression own docs. In the porting guide it makes no sense: there's no "aforementioned" man page, and explaining the parts that compose a regular expression is a "non sequitur", not interesting for the user in that context.
      4. "There is no replacement for the CaretMode enumeration. The QRegularExpression::AnchoredMatchOption match option can be used to emulate the QRegExp::CaretAtOffset behavior. There is no equivalent for the other QRegExp::CaretMode modes."
        • This used to be in its own section. Why did the section got removed and this merged in the text? Looks like a random nitpick in the middle of the text.
      5. "Please note though that not all shell like wildcard pattern might be translated in a way you would expect it. The following example code will silently break if simply converted using the above mentioned function:"
        • Explain what's broken, precisely, and why. What can the user do? What patterns should they check? Knowing "something may break" is not very useful.
      6. "Forward searching inside a string was usually implemented with a loop using QRegExp::indexIn and a growing offset, but can now be easily implemented with QRegularExpressionMatchIterator or QString::indexOf."
        • No, you can't use indexOf and a growing index. You must use QRegularExpressionMatchIterator. Proof: try a pattern that can match a zero-length sequence, and you'll end up in endless recursion. It's written in QRegularExpression docs!
      7. "Searching backwards"
        • Kill it with fire! You don't search backwards with a regexp, you'll do O(matches²) matches!
      8. "exactMatch vs. match.hasMatch"
      9. "Different pattern syntax"
        • This is missing parts when compared to QRegExp docs. Again, just remove all of this and overwrite it with QRegExp docs.

      Copyright

      I happen to have a personal copyright for all the QRegularExpression docs, so please also lift it from qregularexpression.cpp to whatever else those docs end up in.

        Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

            People

            Assignee:
            docteam Qt Documentation Team
            Reporter:
            peppe Giuseppe D'Angelo
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:

                Gerrit Reviews

                There are no open Gerrit changes