# HG changeset patch
# Parent  4e186581fea7f82ce4688560e577d059eafccf01
Issue #15984: Correct the documentation for PyUnicode_FromObject()

diff -r 4e186581fea7 Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst	Wed May 01 00:17:45 2013 +0200
+++ b/Doc/c-api/unicode.rst	Wed Apr 13 11:17:05 2016 +0000
@@ -727,8 +727,11 @@
 
 .. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
 
-   Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
-   throughout the interpreter whenever coercion to Unicode is needed.
+   Copy an instance of a Unicode subtype to a new true Unicode object if
+   necessary. If *obj* is already a true Unicode object (not a subtype),
+   return the reference with incremented refcount.
+
+   Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
 
 
 Locale Encoding
diff -r 4e186581fea7 Include/unicodeobject.h
--- a/Include/unicodeobject.h	Wed May 01 00:17:45 2013 +0200
+++ b/Include/unicodeobject.h	Wed Apr 13 11:17:05 2016 +0000
@@ -864,13 +864,9 @@
     const char *errors          /* error handling */
     );
 
-/* Coerce obj to an Unicode object and return a reference with
-   *incremented* refcount.
-
-   Unicode objects are passed back as-is (subclasses are converted to
-   true Unicode objects), all other objects are delegated to
-   PyUnicode_FromEncodedObject(obj, NULL, "strict") which results in
-   using UTF-8 encoding as basis for decoding the object.
+/* Copy an instance of a Unicode subtype to a new true Unicode object if
+   necessary. If obj is already a true Unicode object (not a subtype), return
+   the reference with *incremented* refcount.
 
    The API returns NULL in case of an error. The caller is responsible
    for decref'ing the returned objects.