Document the potential widening effect of upper-casing

In QChar we don't return the upper-case from when it's not
representable as a single QChar; for strings, the uppercase string may
be longer than the original.

Pick-to: 6.7 6.5 6.2 5.15
Change-Id: I57bb1412d79d579a9cc4dc6bdbb839e56f9ea0a8
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 65eb1c5579ec56d15583b4af45b50fddd3c799a6)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/text/qchar.cpp

@@ -1588,6 +1588,11 @@ char32_t QChar::toLower(char32_t ucs4) noexcept
 
     Returns the uppercase equivalent if the character is lowercase or titlecase;
     otherwise returns the character itself.
+
+    \note This function also returns the original character in the rare case of
+    the uppercase form of the character requiring two or more characters.
+
+    \sa QString::toUpper()
 */
 
 /*!
@@ -1596,7 +1601,12 @@ char32_t QChar::toLower(char32_t ucs4) noexcept
     by \a ucs4 if the character is lowercase or titlecase; otherwise returns
     the character itself.
 
+    \note This function also returns the original character in the rare case of
+    the uppercase form of the character requiring two or more characters.
+
     \note Before Qt 6, this function took a \c uint argument and returned \c uint.
+
+    \sa QString::toUpper()
 */
 char32_t QChar::toUpper(char32_t ucs4) noexcept
 {

src/corelib/text/qlocale.cpp

@@ -3403,6 +3403,9 @@ Qt::LayoutDirection QLocale::textDirection() const
   Otherwise the conversion may be done in a platform-dependent manner,
   with QString::toUpper() as a generic fallback.
 
+  \note In some cases the uppercase form of a string may be longer than the
+  original.
+
   \sa QString::toUpper()
 */
 QString QLocale::toUpper(const QString &str) const

src/corelib/text/qstring.cpp

@@ -7239,7 +7239,10 @@ QString QString::toCaseFolded_helper(QString &str)
     \snippet qstring/main.cpp 81
 
     The case conversion will always happen in the 'C' locale. For
-    locale-dependent case folding use QLocale::toUpper()
+    locale-dependent case folding use QLocale::toUpper().
+
+    \note In some cases the uppercase form of a string may be longer than the
+    original.
 
     \sa toLower(), QLocale::toLower()
 */