Issue #9738: document encodings of unicode functions

Victor Stinner · Victor Stinner · commit dc2081f72bfe · 2010-12-27T01:49:29.000Z
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
@@ -1063,7 +1063,8 @@ They all return *NULL* or ``-1`` if an exception occurs.
 .. c:function:: int PyUnicode_CompareWithASCIIString(PyObject *uni, char *string)
 
    Compare a unicode object, *uni*, with *string* and return -1, 0, 1 for less
-   than, equal, and greater than, respectively.
+   than, equal, and greater than, respectively. *string* is an ASCII-encoded
+   string (it is interpreted as ISO-8859-1).
 
 
 .. c:function:: int PyUnicode_RichCompare(PyObject *left,  PyObject *right,  int op)
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
@@ -443,14 +443,14 @@ PyAPI_FUNC(PyObject*) PyUnicode_FromUnicode(
 
 /* Similar to PyUnicode_FromUnicode(), but u points to UTF-8 encoded bytes */
 PyAPI_FUNC(PyObject*) PyUnicode_FromStringAndSize(
-    const char *u,        /* char buffer */
-    Py_ssize_t size       /* size of buffer */
+    const char *u              /* UTF-8 encoded string */
+    Py_ssize_t size            /* size of buffer */
     );
 
 /* Similar to PyUnicode_FromUnicode(), but u points to null-terminated
    UTF-8 encoded bytes */
 PyAPI_FUNC(PyObject*) PyUnicode_FromString(
-    const char *u        /* string */
+    const char *u              /* UTF-8 encoded string */
     );
 
 /* Return a read-only pointer to the Unicode object's internal
@@ -551,7 +551,9 @@ PyAPI_FUNC(PyObject *) _PyUnicode_FormatAdvanced(PyObject *obj,
 
 PyAPI_FUNC(void) PyUnicode_InternInPlace(PyObject **);
 PyAPI_FUNC(void) PyUnicode_InternImmortal(PyObject **);
-PyAPI_FUNC(PyObject *) PyUnicode_InternFromString(const char *);
+PyAPI_FUNC(PyObject *) PyUnicode_InternFromString(
+    const char *u              /* UTF-8 encoded string */
+    );
 #ifndef Py_LIMITED_API
 PyAPI_FUNC(void) _Py_ReleaseInternedUnicodeStrings(void);
 #endif
@@ -1455,7 +1457,7 @@ PyAPI_FUNC(int) PyUnicode_Compare(
 
 PyAPI_FUNC(int) PyUnicode_CompareWithASCIIString(
     PyObject *left,
-    const char *right
+    const char *right           /* ASCII-encoded string */
     );
 
 /* Rich compare two strings and return one of the following:
