Improve the documentation of compare() overloads for string-like types

Also update the QCollator::compare() docs for consistency.

Task-number: QTBUG-114822
Change-Id: I5fca896cacedd93ce5a4a1a8aead1986a21f6993
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>

src/corelib/text/qanystringview.cpp

@@ -571,7 +571,9 @@ QT_BEGIN_NAMESPACE
 /*!
     \fn QAnyStringView::compare(QAnyStringView lhs, QAnyStringView rhs, Qt::CaseSensitivity cs)
 
-    Returns an integer that compares to zero as \a lhs compares to \a rhs.
+    Compares the string view \a lhs with the string view \a rhs and returns a
+    negative integer if \a lhs is less than \a rhs, a positive integer if it is
+    greater than \a rhs, and zero if they are equal.
 
     If \a cs is Qt::CaseSensitive (the default), the comparison is case sensitive;
     otherwise the comparison is case-insensitive.

src/corelib/text/qcollator.cpp

@@ -317,8 +317,8 @@ bool QCollator::ignorePunctuation() 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.
+    Returns a negative integer if \a s1 is less than \a s2, a positive integer
+    if it is greater than \a s2, and zero if they are equal.
 */
 
 /*!
@@ -341,8 +341,9 @@ bool QCollator::ignorePunctuation() const
     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 a negative integer if \a s1 is less than \a s2, a positive integer
+    if it is greater than \a s2, and zero if they are equal.
+
 
     \note In Qt versions prior to 6.4, the length arguments were of type
     \c{int}, not \c{qsizetype}.

src/corelib/text/qlatin1stringview.qdoc

@@ -404,9 +404,10 @@
     \fn int QLatin1StringView::compare(QChar ch, Qt::CaseSensitivity cs) const
     \since 5.14
 
-    Returns an integer that compares to zero as this string view compares
-    to the UTF-16 string viewed by \a str, the Latin-1 string viewed by \a l1,
-    or the character \a ch, respectively.
+    Compares this string view with UTF-16 string view \a str, Latin-1 string view \a l1,
+    or the character \a ch, respectively. Returns a negative integer if this
+    string is less than \a str, \a l1 or \a ch, returns a positive integer if it
+    is greater than \a str, \a l1 or \a ch, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {search}
 
@@ -417,8 +418,9 @@
     \fn int QLatin1StringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const
     \since 6.5
 
-    Returns an integer that compares to zero as this string view compares to the
-    string view \a str.
+    Compares this string view with \a str and returns a negative integer if
+    this string view is less than \a str, a positive integer if it is greater than
+    \a str, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 

src/corelib/text/qstring.cpp

@@ -6453,9 +6453,9 @@ QString& QString::fill(QChar ch, qsizetype size)
     \fn int QString::compare(const QString &s1, const QString &s2, Qt::CaseSensitivity cs)
     \since 4.2
 
-    Compares \a s1 with \a s2 and returns an integer less than, equal
-    to, or greater than zero if \a s1 is less than, equal to, or
-    greater than \a s2.
+    Compares the string \a s1 with the string \a s2 and returns a negative integer
+    if \a s1 is less than \a s2, a positive integer if it is greater than \a s2,
+    and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 
@@ -6517,10 +6517,9 @@ QString& QString::fill(QChar ch, qsizetype size)
     \overload compare()
     \since 4.2
 
-    Lexically compares this string with the \a other string and
-    returns an integer less than, equal to, or greater than zero if
-    this string is less than, equal to, or greater than the other
-    string.
+    Lexically compares this string with the string \a other and returns
+    a negative integer if this string is less than \a other, a positive
+    integer if it is greater than \a other, and zero if they are equal.
 
     Same as compare(*this, \a other, \a cs).
 */

src/corelib/text/qstringview.cpp

@@ -728,8 +728,9 @@ QT_BEGIN_NAMESPACE
     \fn int QStringView::compare(QStringView str, Qt::CaseSensitivity cs) const
     \since 5.12
 
-    Returns an integer that compares to zero as this string view compares to the
-    string view \a str.
+    Compares this string view with string view \a str and returns a negative integer if
+    this string view is less than \a str, a positive integer if it is greater than
+    \a str, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 
@@ -740,8 +741,9 @@ QT_BEGIN_NAMESPACE
     \fn int QStringView::compare(QUtf8StringView str, Qt::CaseSensitivity cs) const
     \since 6.5
 
-    Returns an integer that compares to zero as this string view compares to the
-    string view \a str.
+    Compares this string view with QUtf8StringView \a str and returns a negative integer if
+    this string view is less than \a str, a positive integer if it is greater than
+    \a str, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 
@@ -754,8 +756,9 @@ QT_BEGIN_NAMESPACE
     \fn int QStringView::compare(QChar ch, Qt::CaseSensitivity cs) const
     \since 5.15
 
-    Returns an integer that compares to zero as this string view compares to the
-    Latin-1 string viewed by \a l1, or the character \a ch, respectively.
+    Compares this string view to the Latin-1 string view \a l1, or the character \a ch.
+    Returns a negative integer if this string view is less than \a l1 or \a ch,
+    a positive integer if it is greater than \a l1 or \a ch, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 

src/corelib/text/qutf8stringview.qdoc

@@ -669,8 +669,9 @@
     \fn int QUtf8StringView::compare(QStringView str, Qt::CaseSensitivity cs) const
     \since 6.5
 
-    Returns an integer that compares to zero as this string view compares to the
-    string view \a str.
+    Compares this string view with \a str and returns a negative integer if
+    this string view is less than \a str, a positive integer if it is greater than
+    \a str, and zero if they are equal.
 
     \include qstring.qdocinc {search-comparison-case-sensitivity} {comparison}
 */