From fb8d604d55cd0d27fd2e33370c092654aa7943ec Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 27 Sep 2024 12:42:23 +0200
Subject: [PATCH] [3.12] GH-95079: document error behaviour for some unicode C
 APIs (GH-95080) (#124662)

(cherry picked from commit b79a21ea429844e84509430e636d808ea9cff244)

Co-authored-by: Max Bachmann <kontakt@maxbachmann.de>
---
 Doc/c-api/unicode.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 54a006c0275..d1e40c1550c 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -345,6 +345,8 @@ APIs:
    This is the recommended way to allocate a new Unicode object.  Objects
    created using this function are not resizable.
 
+   On error, set an exception and return ``NULL``.
+
    .. versionadded:: 3.3
 
 
@@ -598,6 +600,8 @@ APIs:
 
    Return the length of the Unicode object, in code points.
 
+   On error, set an exception and return ``-1``.
+
    .. versionadded:: 3.3
 
 
@@ -641,6 +645,8 @@ APIs:
    not out of bounds, and that the object can be modified safely (i.e. that it
    its reference count is one).
 
+   Return ``0`` on success, ``-1`` on error with an exception set.
+
    .. versionadded:: 3.3
 
 
@@ -650,6 +656,8 @@ APIs:
    Unicode object and the index is not out of bounds, in contrast to
    :c:func:`PyUnicode_READ_CHAR`, which performs no error checking.
 
+   Return character on success, ``-1`` on error with an exception set.
+
    .. versionadded:: 3.3
 
 
@@ -658,6 +666,7 @@ APIs:
 
    Return a substring of *unicode*, from character index *start* (included) to
    character index *end* (excluded).  Negative indices are not supported.
+   On error, set an exception and return ``NULL``.
 
    .. versionadded:: 3.3