Clean up QCollator's documentation and tell fewer lies

Its collation strategy can't be passed to the constructor, so
describing it as initialized with a strategy was misleading.

The "Linux without ICU" disclaimer was poorly phrased and only
mentioned on one of the options; it actually applies to all.

The operator() was marked internal, but the class doc's claim that
QCollator can be used with std::sort() relies on it being callable.

Moved option descriptions to the getters and filled in the missing
ones. Mention the default in all cases.

Added a minimal illustration of how to use a QCollator.

Fixes: QTBUG-72233
Change-Id: Ifa846eca05e8e42aaa08c4947a59a82d8a8a79bc
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 116 insertions, 53 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp
new file mode 100644
index 0000000000..9a2e0dac58
--- /dev/null
+++ b/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QStringList sortedStrings(QStringList seq)
+{
+    QCollator order;
+    std::sort(seq.begin(), seq.end(), order);
+    return seq;
+}
+//! [0]
diff --git a/src/corelib/text/qcollator.cpp b/src/corelib/text/qcollator.cpp
index 6974365cda..46bd64daf5 100644
--- a/src/corelib/text/qcollator.cpp
+++ b/src/corelib/text/qcollator.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Copyright (C) 2013 Aleix Pol Gonzalez <aleixpol@kde.org>
 ** Contact: https://www.qt.io/licensing/
 **
@@ -58,15 +58,19 @@ 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. It can then be used to compare and
+    sort strings in using the ordering appropriate to the locale.
 
-    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 with QString entries.
 
-    In addition to the locale and collation strategy, several optional flags can
-    be set that influence the result of the collation.
+    \snippet code/src_corelib_text_qcollator.cpp 0
+
+    In addition to the locale, several optional flags can be set that influence
+    the result of the collation.
+
+    \note All options are ignored on Linux unless Qt is configured to use ICU
+    (which it usually is).
 */
 
 /*!
@@ -83,7 +87,7 @@ QCollator::QCollator()
 }
 
 /*!
-    Constructs a QCollator from \a locale.
+    Constructs a QCollator using the given \a locale.
 
     \sa setLocale()
 */
@@ -107,7 +111,7 @@ QCollator::QCollator(const QCollator &other)
 }
 
 /*!
-    Destroys the collator.
+    Destroys this collator.
 */
 QCollator::~QCollator()
 {
@@ -178,6 +182,8 @@ void QCollator::detach()
 
 /*!
     Sets the locale of the collator to \a locale.
+
+    \sa locale()
 */
 void QCollator::setLocale(const QLocale &locale)
 {
@@ -190,6 +196,11 @@ void QCollator::setLocale(const QLocale &locale)
 
 /*!
     Returns the locale of the collator.
+
+    Unless supplied to the constructor or by calling setLocale(), the system's
+    default collation locale is used.
+
+    \sa setLocale(), QLocale::collation()
 */
 QLocale QCollator::locale() const
 {
@@ -197,9 +208,7 @@ QLocale QCollator::locale() const
 }
 
 /*!
-    \fn void QCollator::setCaseSensitivity(Qt::CaseSensitivity sensitivity)
-
-    Sets the case \a sensitivity of the collator.
+    Sets the case-sensitivity of the collator to \a cs.
 
     \sa caseSensitivity()
 */
@@ -213,10 +222,15 @@ void QCollator::setCaseSensitivity(Qt::CaseSensitivity cs)
 }
 
 /*!
-    \fn Qt::CaseSensitivity QCollator::caseSensitivity() const
-
     Returns case sensitivity of the collator.
 
+    This defaults to case-sensitive until set.
+
+    \note In the C locale, when case-sensitive, all lower-case letters sort
+    after all upper-case letters, where most locales sort each lower-case letter
+    either immediately before or immediately after its upper-case partner.  Thus
+    "Zap" sorts before "ape" in the C locale but after in most others.
+
     \sa setCaseSensitivity()
 */
 Qt::CaseSensitivity QCollator::caseSensitivity() const
@@ -225,14 +239,7 @@ Qt::CaseSensitivity QCollator::caseSensitivity() const
 }
 
 /*!
-    \fn void QCollator::setNumericMode(bool on)
-
-    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.
-
-    By default this mode is off.
+    Enables numeric sorting mode when \a on is \c true.
 
     \sa numericMode()
 */
@@ -246,9 +253,12 @@ void QCollator::setNumericMode(bool on)
 }
 
 /*!
-    \fn bool QCollator::numericMode() const
+    Returns \c true if numeric sorting is enabled, \c false otherwise.
 
-    Returns \c true if numeric sorting is enabled, false otherwise.
+    When \c true, numerals are recognized as numbers and sorted in arithmetic
+    order; for example, 100 sortes after 99. When \c false, numbers are sorted
+    in lexical order, so that 100 sorts before 99 (because 1 is before 9). By
+    default, this option is disabled.
 
     \sa setNumericMode()
 */
@@ -258,15 +268,7 @@ 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.
-
-    The default is locale dependent.
-
-    \note This method is not currently supported if Qt is configured to not use
-    ICU on Linux.
+    Control whether punctuation and symbols are ignored when collating.
 
     \sa ignorePunctuation()
 */
@@ -280,10 +282,10 @@ void QCollator::setIgnorePunctuation(bool on)
 }
 
 /*!
-    \fn bool QCollator::ignorePunctuation() const
+    Indicates whether punctuation and symbols are ignored when collating.
 
-    Returns \c true if punctuation characters and symbols are ignored when
-    determining sort order.
+    When \c true, strings are compared as if all punctuation and symbols were
+    removed from each string.
 
     \sa setIgnorePunctuation()
 */
@@ -295,7 +297,11 @@ bool QCollator::ignorePunctuation() const
 /*!
     \since 5.13
     \fn bool QCollator::operator()(QStringView s1, QStringView s2) const
-    \internal
+
+    A QCollator can be used as the comparison function of a sorting algorithm.
+    It returns \c true if \a s1 sorts before \a s2, otherwise \c false.
+
+    \sa compare()
 */
 
 /*!
@@ -310,16 +316,13 @@ bool QCollator::ignorePunctuation() const
 #if QT_STRINGVIEW_LEVEL < 2
 /*!
     \fn bool QCollator::operator()(const QString &s1, const QString &s2) const
-    \internal
+    \overload
+    \since 5.2
 */
 
 /*!
     \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.
+    \since 5.2
 */
 int QCollator::compare(const QString &s1, const QString &s2) const
 {
@@ -328,6 +331,7 @@ int QCollator::compare(const QString &s1, const QString &s2) const
 
 /*!
     \overload
+    \since 5.2
 
     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.
@@ -369,7 +373,7 @@ int QCollator::compare(const QChar *s1, int len1, const QChar *s2, int len2) con
     \ingroup string-processing
     \ingroup shared
 
-    \sa QCollator, QCollator::sortKey()
+    \sa QCollator, QCollator::sortKey(), compare()
 */
 
 /*!
@@ -413,11 +417,11 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
 */
 
 /*!
-    \fn bool operator<(const QCollatorSortKey &lhs, const QCollatorSortKey &rhs)
-    \relates QCollatorSortKey
+    \fn bool QCollatorSortKey::operator<(const QCollatorSortKey &lhs, const QCollatorSortKey &rhs)
 
-    According to the QCollator that created the keys, returns \c true if \a lhs
-    should be sorted before \a rhs; otherwise returns \c false.
+    Both keys must have been created by the same QCollator's sortKey(). Returns
+    \c true if \a lhs should be sorted before \a rhs, according to the QCollator
+    that created them; otherwise returns \c false.
 
     \sa QCollatorSortKey::compare()
 */
@@ -431,11 +435,12 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
 /*!
     \fn int QCollatorSortKey::compare(const QCollatorSortKey &otherKey) const
 
-    Compares this key to \a otherKey.
+    Compares this key to \a otherKey, which must have been created by the same
+    QCollator's sortKey() as this key. The comparison is performed in accordance
+    with that QCollator's sort order.
 
-    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.
+    Returns a negative value if this key sorts before \a otherKey, 0 if the two
+    keys are equal or a positive value if this key sorts after \a otherKey.
 
     \sa operator<()
 */