[3.14] gh-141004: Document PyOS_mystr(n)icmp (GH-141760) (#141947)

gh-141004: Document `PyOS_mystr(n)icmp` (GH-141760)
(cherry picked from commit f445c45)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>

Author: 3 people

Doc/c-api/conversion.rst

@@ -162,16 +162,33 @@ The following functions provide locale-independent string to number conversions.
    .. versionadded:: 3.1
 
 
-.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
+.. c:function:: int PyOS_mystricmp(const char *str1, const char *str2)
+                int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)
 
-   Case insensitive comparison of strings. The function works almost
-   identically to :c:func:`!strcmp` except that it ignores the case.
+   Case insensitive comparison of strings. These functions work almost
+   identically to :c:func:`!strcmp` and :c:func:`!strncmp` (respectively),
+   except that they ignore the case of ASCII characters.
 
+   Return ``0`` if the strings are equal, a negative value if *str1* sorts
+   lexicographically before *str2*, or a positive value if it sorts after.
 
-.. c:function:: int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t  size)
+   In the *str1* or *str2* arguments, a NUL byte marks the end of the string.
+   For :c:func:`!PyOS_mystrnicmp`, the *size* argument gives the maximum size
+   of the string, as if NUL was present at the index given by *size*.
 
-   Case insensitive comparison of strings. The function works almost
-   identically to :c:func:`!strncmp` except that it ignores the case.
+   These functions do not use the locale.
+
+
+.. c:function:: int PyOS_stricmp(const char *str1, const char *str2)
+                int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t  size)
+
+   Case insensitive comparison of strings.
+
+   On Windows, these are aliases of :c:func:`!stricmp` and :c:func:`!strnicmp`,
+   respectively.
+
+   On other platforms, they are aliases of :c:func:`PyOS_mystricmp` and
+   :c:func:`PyOS_mystrnicmp`, respectively.
 
 
 Character classification and conversion

Misc/NEWS.d/3.10.0a1.rst

@@ -3275,8 +3275,8 @@ Types created with :c:func:`PyType_FromSpec` now make any signature in their
 .. nonce: u6Xfr2
 .. section: C API
 
-Fix bug in PyOS_mystrnicmp and PyOS_mystricmp that incremented pointers
-beyond the end of a string.
+Fix bug in :c:func:`PyOS_mystrnicmp` and :c:func:`PyOS_mystricmp` that
+incremented pointers beyond the end of a string.
 
 ..