Clean up docs of qbytearray.cpp's C-string functions

Details of MSVC version became irrelevant some time ago; the code now
just tests for MSVC. In any case, the reader doesn't need to know how
the function is implemented, as long as it does what it claims to do.

We do not, in fact, use a random number source when generating the
return value for comparisons involving only one nullptr; we quite
consistently treat the nullptr as less than the other string. Make
explicit that this is true even if the other is empty.

Change-Id: Ifd9b00fdf8e814fcf933a05821201670fecfd646
Reviewed-by: Andrei Golubev <andrei.golubev@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 12 insertions, 20 deletions

diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index de9bf26a9c..1a0237c225 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -150,10 +150,6 @@ char *qstrcpy(char *dst, const char *src)
 
     \note If \a dst and \a src overlap, the behavior is undefined.
 
-    \note When compiling with Visual C++ compiler version 14.00
-    (Visual C++ 2005) or later, internally the function strncpy_s
-    will be used.
-
     \sa qstrcpy()
 */
 
@@ -204,10 +200,9 @@ char *qstrncpy(char *dst, const char *src, uint len)
     is less than \a str2, 0 if \a str1 is equal to \a str2 or a
     positive value if \a str1 is greater than \a str2.
 
-    Special case 1: Returns 0 if \a str1 and \a str2 are both \nullptr.
-
-    Special case 2: Returns an arbitrary non-zero value if \a str1 is
-    \nullptr or \a str2 is \nullptr (but not both).
+    If both strings are \nullptr, they are deemed equal; otherwise, if either is
+    \nullptr, it is treated as less than the other (even if the other is an
+    empty string).
 
     \sa qstrncmp(), qstricmp(), qstrnicmp(), {Character Case}, QByteArray::compare()
 */
@@ -229,10 +224,9 @@ int qstrcmp(const char *str1, const char *str2)
     str1 is equal to \a str2 or a positive value if \a str1 is greater
     than \a str2.
 
-    Special case 1: Returns 0 if \a str1 and \a str2 are both \nullptr.
-
-    Special case 2: Returns a random non-zero value if \a str1 is \nullptr
-    or \a str2 is \nullptr (but not both).
+    If both strings are \nullptr, they are deemed equal; otherwise, if either is
+    \nullptr, it is treated as less than the other (even if the other is an
+    empty string or \a len is 0).
 
     \sa qstrcmp(), qstricmp(), qstrnicmp(), {Character Case}, QByteArray::compare()
 */
@@ -248,10 +242,9 @@ int qstrcmp(const char *str1, const char *str2)
     str1 is equal to \a str2 or a positive value if \a str1 is greater
     than \a str2.
 
-    Special case 1: Returns 0 if \a str1 and \a str2 are both \nullptr.
-
-    Special case 2: Returns a random non-zero value if \a str1 is \nullptr
-    or \a str2 is \nullptr (but not both).
+    If both strings are \nullptr, they are deemed equal; otherwise, if either is
+    \nullptr, it is treated as less than the other (even if the other is an
+    empty string).
 
     \sa qstrcmp(), qstrncmp(), qstrnicmp(), {Character Case}, QByteArray::compare()
 */
@@ -338,10 +331,9 @@ int qstricmp(const char *str1, const char *str2)
     is equal to \a str2 or a positive value if \a str1 is greater than \a
     str2.
 
-    Special case 1: Returns 0 if \a str1 and \a str2 are both \nullptr.
-
-    Special case 2: Returns a random non-zero value if \a str1 is \nullptr
-    or \a str2 is \nullptr (but not both).
+    If both strings are \nullptr, they are deemed equal; otherwise, if either is
+    \nullptr, it is treated as less than the other (even if the other is an
+    empty string or \a len is 0).
 
     \sa qstrcmp(), qstrncmp(), qstricmp(), {Character Case}, QByteArray::compare()
 */