QCollator: clarify the POSIX backend limitations

This clarifies what doesn't work, that we print a warning, and that it
applies to all Unix systems aside from macOS, not just Linux.

Fixes: QTBUG-115852
Pick-to: 6.6
Change-Id: I80612a7d275c41f1baf0fffd1779701e98e7552d
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

src/corelib/text/qcollator.cpp

@@ -57,9 +57,25 @@ Q_GLOBAL_STATIC(QThreadStorage<GenerationalCollator>, defaultCollator)
     In addition to the locale, several optional flags can be set that influence
     the result of the collation.
 
-    \note On Linux, Qt is normally compiled to use ICU. When it isn't, all
-    options are ignored and the only supported locales are the system default
-    (that \c{setlocale(LC_COLLATE, nullptr)} would report) and the "C" locale.
+    \section1 POSIX fallback implementation
+
+    On Unix systems, Qt is normally compiled to use ICU (except for \macos,
+    where Qt defaults to using an equivalent Apple API). However, if ICU was
+    not available at compile time or explicitly disabled, Qt will use a
+    fallback backend that uses the POSIX API only. This backend has several
+    limitations:
+
+    \list
+      \li Only the QLocale::c() and QLocale::system() locales are supported.
+          Consult the POSIX and C Standard Library manuals for the
+          \c{<locale.h>} header for more information on the system locale.
+      \li caseSensitivity() is not supported: only case-sensitive collation
+          can be performed.
+      \li numericMode() and ignorePunctuation() are not supported.
+    \endlist
+
+    The use of any of the unsupported options will cause a warning to be
+    printed to the application's output.
 */
 
 /*!