bpo-39560: Document PyUnicode_FromKindAndData() kind transformation (GH-23848)

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 8322d3da76dca465d4f3cf4c7f2c3f496b6d83c4..ddc2346e92dc08b31b2e70627b89b17acb8f6b3c 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -421,6 +421,12 @@ APIs:
    :c:func:`PyUnicode_KIND`).  The *buffer* must point to an array of *size*
    units of 1, 2 or 4 bytes per character, as given by the kind.
 
+   If necessary, the input *buffer* is copied and transformed into the
+   canonical representation.  For example, if the *buffer* is a UCS4 string
+   (:c:macro:`PyUnicode_4BYTE_KIND`) and it consists only of codepoints in
+   the UCS1 range, it will be transformed into UCS1
+   (:c:macro:`PyUnicode_1BYTE_KIND`).
+
    .. versionadded:: 3.3