[Python-checkins] bpo-39560: Document PyUnicode_FromKindAndData() kind transformation (GH-23848)

[nanjekyejoannah]

https://github.com/python/cpython/commit/4eed2821d40373345ed133b2b8d912fef59acab7
commit: 4eed2821d40373345ed133b2b8d912fef59acab7
branch: main
author: Zackery Spytz <zspytz at gmail.com>
committer: nanjekyejoannah <33177550+nanjekyejoannah at users.noreply.github.com>
date: 2021-06-03T10:33:44-03:00
summary:

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

files:
M Doc/c-api/unicode.rst

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 8322d3da76dca4..ddc2346e92dc08 100644
--- 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