Bug #1541682: Fix example in the "Refcount details" API docs.

Additionally, remove a faulty example showing PySequence_SetItem applied
to a newly created list object and add notes that this isn't a good idea.

Doc/api/abstract.tex

@@ -5,6 +5,10 @@ of their type, or with wide classes of object types (e.g. all
 numerical types, or all sequence types).  When used on object types
 for which they do not apply, they will raise a Python exception.
 
+It is not possible to use these functions on objects that are not properly
+initialized, such a list object that has been created by
+\cfunction{PyList_New()}, but whose items have not been set to some
+non-\code{NULL} value yet.
 
 \section{Object Protocol \label{object}}
 

Doc/api/concrete.tex

@@ -1840,6 +1840,11 @@ format.
 \begin{cfuncdesc}{PyObject*}{PyList_New}{Py_ssize_t len}
   Return a new list of length \var{len} on success, or \NULL{} on
   failure.
+  \note{If \var{length} is greater than zero, the returned list object's
+        items are set to \code{NULL}.  Thus you cannot use abstract
+        API functions such as \cfunction{PySequence_SetItem()} on it
+        or expose it to Python code before setting all items to a
+        real object with \cfunction{PyList_SetItem()}.}
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{Py_ssize_t}{PyList_Size}{PyObject *list}

Doc/api/intro.tex

@@ -225,25 +225,10 @@ immutable data type.  You should only use
 \cfunction{PyTuple_SetItem()} for tuples that you are creating
 yourself.
 
-Equivalent code for populating a list can be written using 
+Equivalent code for populating a list can be written using
-\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.  Such code
+\cfunction{PyList_New()} and \cfunction{PyList_SetItem()}.
-can also use \cfunction{PySequence_SetItem()}; this illustrates the
-difference between the two (the extra \cfunction{Py_DECREF()} calls):
 
-\begin{verbatim}
+However, in practice, you will rarely use these ways of
-PyObject *l, *x;
-
-l = PyList_New(3);
-x = PyInt_FromLong(1L);
-PySequence_SetItem(l, 0, x); Py_DECREF(x);
-x = PyInt_FromLong(2L);
-PySequence_SetItem(l, 1, x); Py_DECREF(x);
-x = PyString_FromString("three");
-PySequence_SetItem(l, 2, x); Py_DECREF(x);
-\end{verbatim}
-
-You might find it strange that the ``recommended'' approach takes more
-code.  However, in practice, you will rarely use these ways of
 creating and populating a tuple or list.  There's a generic function,
 \cfunction{Py_BuildValue()}, that can create most common objects from
 C values, directed by a \dfn{format string}.  For example, the
@@ -251,10 +236,10 @@ above two blocks of code could be replaced by the following (which
 also takes care of the error checking):
 
 \begin{verbatim}
-PyObject *t, *l;
+PyObject *tuple, *list;
 
-t = Py_BuildValue("(iis)", 1, 2, "three");
+tuple = Py_BuildValue("(iis)", 1, 2, "three");
-l = Py_BuildValue("[iis]", 1, 2, "three");
+list = Py_BuildValue("[iis]", 1, 2, "three");
 \end{verbatim}
 
 It is much more common to use \cfunction{PyObject_SetItem()} and
@@ -276,8 +261,12 @@ set_all(PyObject *target, PyObject *item)
     if (n < 0)
         return -1;
     for (i = 0; i < n; i++) {
-        if (PyObject_SetItem(target, i, item) < 0)
+        PyObject *index = PyInt_FromLong(i);
+        if (!index)
             return -1;
+        if (PyObject_SetItem(target, index, item) < 0)
+            return -1;
+        Py_DECREF(index);
     }
     return 0;
 }

Misc/NEWS

@@ -31,6 +31,10 @@ Tests
 Documentation
 -------------
 
+- Bug #1541682: Fix example in the "Refcount details" API docs.
+  Additionally, remove a faulty example showing PySequence_SetItem applied
+  to a newly created list object and add notes that this isn't a good idea.
+
 
 Build
 -----