Clean up the QCollator code and comments

Broke over-long lines.  Reflowed documentation, refined a phrasing,
corrected some out of date details and typos.

Change-Id: Ic3835bb198bd062f85b3c466b56dc9636d4d3fe4
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 69 insertions, 51 deletions

diff --git a/src/corelib/tools/qcollator.cpp b/src/corelib/tools/qcollator.cpp
index f2c9c61c99..d73eb0d07c 100644
--- a/src/corelib/tools/qcollator.cpp
+++ b/src/corelib/tools/qcollator.cpp
@@ -59,20 +59,21 @@ QT_BEGIN_NAMESPACE
     \ingroup string-processing
     \ingroup shared
 
-    QCollator is initialized with a QLocale and an optional collation strategy. It tries to
-    initialize the collator with the specified values. The collator can then be used to compare
-    and sort strings in a locale dependent fashion.
+    QCollator is initialized with a QLocale and an optional collation strategy.
+    It tries to initialize the collator with the specified values. The collator
+    can then be used to compare and sort strings in a locale dependent fashion.
 
-    A QCollator object can be used together with template based sorting algorithms such as std::sort
-    to sort a list of QStrings.
+    A QCollator object can be used together with template based sorting
+    algorithms such as std::sort to sort a list of QStrings.
 
-    In addition to the locale and collation strategy, several optional flags can be set that influence
-    the result of the collation.
+    In addition to the locale and collation strategy, several optional flags can
+    be set that influence the result of the collation.
 */
 
 /*!
-    Constructs a QCollator from \a locale. If \a locale is not specified
-    the system's default locale is used.
+    Constructs a QCollator for \a locale.
+
+    If \a locale is not specified, the system's default locale is used.
 
     \sa setLocale()
  */
@@ -128,9 +129,9 @@ QCollator &QCollator::operator=(const QCollator &other)
 
     Move constructor. Moves from \a other into this collator.
 
-    Note that a moved-from QCollator can only be destroyed or assigned
-    to. The effect of calling other functions than the destructor or
-    one of the assignment operators is undefined.
+    Note that a moved-from QCollator can only be destroyed or assigned to.
+    The effect of calling other functions than the destructor or one of the
+    assignment operators is undefined.
 */
 
 /*!
@@ -138,9 +139,9 @@ QCollator &QCollator::operator=(const QCollator &other)
 
     Move-assigns from \a other to this collator.
 
-    Note that a moved-from QCollator can only be destroyed or assigned
-    to. The effect of calling other functions than the destructor or
-    one of the assignment operators is undefined.
+    Note that a moved-from QCollator can only be destroyed or assigned to.
+    The effect of calling other functions than the destructor or one of the
+    assignment operators is undefined.
 */
 
 /*!
@@ -218,7 +219,8 @@ Qt::CaseSensitivity QCollator::caseSensitivity() const
 
     Enables numeric sorting mode when \a on is set to true.
 
-    This will enable proper sorting of numeric digits, so that e.g. 100 sorts after 99.
+    This will enable proper sorting of numeric digits, so that e.g. 100 sorts
+    after 99.
 
     By default this mode is off.
 
@@ -248,11 +250,13 @@ bool QCollator::numericMode() const
 /*!
     \fn void QCollator::setIgnorePunctuation(bool on)
 
-    If \a on is set to true, punctuation characters and symbols are ignored when determining sort order.
+    If \a on is set to true, punctuation characters and symbols are ignored when
+    determining sort order.
 
     The default is locale dependent.
 
-    \note This method is not currently supported if Qt is configured to not use ICU on Linux.
+    \note This method is not currently supported if Qt is configured to not use
+    ICU on Linux.
 
     \sa ignorePunctuation()
  */
@@ -268,7 +272,8 @@ void QCollator::setIgnorePunctuation(bool on)
 /*!
     \fn bool QCollator::ignorePunctuation() const
 
-    Returns \c true if punctuation characters and symbols are ignored when determining sort order.
+    Returns \c true if punctuation characters and symbols are ignored when
+    determining sort order.
 
     \sa setIgnorePunctuation()
  */
@@ -287,9 +292,11 @@ bool QCollator::ignorePunctuation() const
     \since 5.13
     \fn int QCollator::compare(QStringView s1, QStringView s2) const
 
-    Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero
-    depending on whether \a s1 sorts before, with or after \a s2.
- */
+    Compares \a s1 with \a s2.
+
+    Returns an integer less than, equal to, or greater than zero depending on
+    whether \a s1 sorts before, with or after \a s2.
+*/
 #if QT_STRINGVIEW_LEVEL < 2
 /*!
     \fn bool QCollator::operator()(const QString &s1, const QString &s2) const
@@ -299,9 +306,11 @@ bool QCollator::ignorePunctuation() const
 /*!
     \overload
 
-    Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero
-    depending on whether \a s1 sorts before, with or after \a s2.
- */
+    Compares \a s1 with \a s2.
+
+    Returns an integer less than, equal to, or greater than zero depending on
+    whether \a s1 sorts before, with or after \a s2.
+*/
 int QCollator::compare(const QString &s1, const QString &s2) const
 {
     return compare(QStringView(s1), QStringView(s2));
@@ -310,8 +319,10 @@ int QCollator::compare(const QString &s1, const QString &s2) const
 /*!
     \overload
 
-    Compares \a s1 with \a s2. Returns an integer less than, equal to, or greater than zero
-    depending on whether \a s1 sorts before, with or after \a s2.
+    Compares \a s1 with \a s2.
+
+    Returns an integer less than, equal to, or greater than zero depending on
+    whether \a s1 sorts before, with or after \a s2.
  */
 int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const
 {
@@ -321,11 +332,11 @@ int QCollator::compare(const QStringRef &s1, const QStringRef &s2) const
 /*!
     \overload
 
-    Compares \a s1 with \a s2. \a len1 and \a len2 specify the length of the
-    QChar arrays pointer to by \a s1 and \a s2.
+    Compares \a s1 with \a s2. \a len1 and \a len2 specify the lengths of the
+    QChar arrays pointed to by \a s1 and \a s2.
 
-    Returns an integer less than, equal to, or greater than zero
-    depending on whether \a s1 sorts before, with or after \a s2.
+    Returns an integer less than, equal to, or greater than zero depending on
+    whether \a s1 sorts before, with or after \a s2.
 */
 int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) const
 {
@@ -339,9 +350,9 @@ int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) con
     Returns a sortKey for \a string.
 
     Creating the sort key is usually somewhat slower, than using the compare()
-    methods directly. But if the string is compared repeatedly (e.g. when sorting
-    a whole list of strings), it's usually faster to create the sort keys for each
-    string and then sort using the keys.
+    methods directly. But if the string is compared repeatedly (e.g. when
+    sorting a whole list of strings), it's usually faster to create the sort
+    keys for each string and then sort using the keys.
 
     \note Not supported with the C (a.k.a. POSIX) locale on Darwin.
  */
@@ -353,8 +364,8 @@ int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) con
 
     \since 5.2
 
-    The QCollatorSortKey class is always created by QCollator::sortKey()
-    and is used for fast strings collation, for example when collating many strings.
+    The QCollatorSortKey class is always created by QCollator::sortKey() and is
+    used for fast strings collation, for example when collating many strings.
 
     \reentrant
     \ingroup i18n
@@ -423,9 +434,11 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
 /*!
     \fn int QCollatorSortKey::compare(const QCollatorSortKey &otherKey) const
 
-    Compares the key to \a otherKey. Returns a negative value if the key
-    is less than \a otherKey, 0 if the key is equal to \a otherKey or a
-    positive value if the key is greater than \a otherKey.
+    Compares this key to \a otherKey.
+
+    Returns a negative value if the key is less than \a otherKey, 0 if the key
+    is equal to \a otherKey or a positive value if the key is greater than \a
+    otherKey.
 
     \sa operator<()
  */
diff --git a/src/corelib/tools/qcollator_icu.cpp b/src/corelib/tools/qcollator_icu.cpp
index eb0ba33676..8acda45070 100644
--- a/src/corelib/tools/qcollator_icu.cpp
+++ b/src/corelib/tools/qcollator_icu.cpp
@@ -78,7 +78,8 @@ void QCollatorPrivate::init()
     // and does case sensitive comparison.
     // UCOL_QUATERNARY is used as default in a few languages such as Japanese to take care of some
     // additional differences in those languages.
-    UColAttributeValue val = (caseSensitivity == Qt::CaseSensitive) ? UCOL_DEFAULT_STRENGTH : UCOL_SECONDARY;
+    UColAttributeValue val = (caseSensitivity == Qt::CaseSensitive)
+        ? UCOL_DEFAULT_STRENGTH : UCOL_SECONDARY;
 
     status = U_ZERO_ERROR;
     ucol_setAttribute(collator, UCOL_STRENGTH, val, &status);
@@ -91,7 +92,8 @@ void QCollatorPrivate::init()
         qWarning("ucol_setAttribute: numeric collation failed: %d", status);
 
     status = U_ZERO_ERROR;
-    ucol_setAttribute(collator, UCOL_ALTERNATE_HANDLING, ignorePunctuation ? UCOL_SHIFTED : UCOL_NON_IGNORABLE, &status);
+    ucol_setAttribute(collator, UCOL_ALTERNATE_HANDLING,
+                      ignorePunctuation ? UCOL_SHIFTED : UCOL_NON_IGNORABLE, &status);
     if (U_FAILURE(status))
         qWarning("ucol_setAttribute: Alternate handling failed: %d", status);
 
diff --git a/src/corelib/tools/qcollator_macx.cpp b/src/corelib/tools/qcollator_macx.cpp
index ff127a041d..071d7c048f 100644
--- a/src/corelib/tools/qcollator_macx.cpp
+++ b/src/corelib/tools/qcollator_macx.cpp
@@ -71,7 +71,6 @@ void QCollatorPrivate::init()
         qWarning("Couldn't initialize the locale (%d)", int(status));
 
     UInt32 options = 0;
-
     if (caseSensitivity == Qt::CaseInsensitive)
         options |= kUCCollateCaseInsensitiveMask;
     if (numericMode)
@@ -125,13 +124,14 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
     //Documentation recommends having it 5 times as big as the input
     QVector<UCCollationValue> ret(string.size() * 5);
     ItemCount actualSize;
-    int status = UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(),
-                                   ret.size(), &actualSize, ret.data());
+    int status = UCGetCollationKey(d->collator,
+                                   reinterpret_cast<const UniChar *>(string.constData()),
+                                   string.count(), ret.size(), &actualSize, ret.data());
 
-    ret.resize(actualSize+1);
+    ret.resize(actualSize + 1);
     if (status == kUCOutputBufferTooSmall) {
-        UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()), string.count(),
-                          ret.size(), &actualSize, ret.data());
+        UCGetCollationKey(d->collator, reinterpret_cast<const UniChar *>(string.constData()),
+                          string.count(), ret.size(), &actualSize, ret.data());
     }
     ret[actualSize] = 0;
     return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret)));
diff --git a/src/corelib/tools/qcollator_win.cpp b/src/corelib/tools/qcollator_win.cpp
index 9cbdd96ee0..4adbf4adf8 100644
--- a/src/corelib/tools/qcollator_win.cpp
+++ b/src/corelib/tools/qcollator_win.cpp
@@ -94,9 +94,10 @@ int QCollator::compare(QStringView s1, QStringView s2) const
         d->init();
 
     //* from Windows documentation *
-    // Returns one of the following values if successful. To maintain the C runtime convention of
-    // comparing strings, the value 2 can be subtracted from a nonzero return value. Then, the
-    // meaning of <0, ==0, and >0 is consistent with the C runtime.
+    // Returns one of the following values if successful. To maintain the C
+    // runtime convention of comparing strings, the value 2 can be subtracted
+    // from a nonzero return value. Then, the meaning of <0, ==0, and >0 is
+    // consistent with the C runtime.
 
 #ifndef USE_COMPARESTRINGEX
     return CompareString(d->localeID, d->collator,
@@ -137,7 +138,9 @@ QCollatorSortKey QCollator::sortKey(const QString &string) const
                            NULL, NULL, 0);
 #endif
     if (finalSize == 0) {
-        qWarning() << "there were problems when generating the ::sortKey by LCMapStringW with error:" << GetLastError();
+        qWarning()
+            << "there were problems when generating the ::sortKey by LCMapStringW with error:"
+            << GetLastError();
     }
     return QCollatorSortKey(new QCollatorSortKeyPrivate(std::move(ret)));
 }