Document Pyerr_Warn().
Add an XXX comment at the beginning expressing disappointment over the
confusing way refcount behavior of arguments is documented.
diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat
index aace695..0d8d6af 100644
--- a/Doc/api/refcounts.dat
+++ b/Doc/api/refcounts.dat
@@ -21,6 +21,13 @@
# always return NULL. This is used by some of the PyErr_*() functions, in
# particular.
+# XXX NOTE: the 0/+1/-1 refcount information for arguments is
+# confusing! Much more useful would be to indicate whether the
+# function "steals" a reference to the argument or not. Take for
+# example PyList_SetItem(list, i, item). This lists as a 0 change for
+# both the list and the item arguments. However, in fact it steals a
+# reference to the item argument!
+
# The parameter names are as they appear in the API manual, not the source
# code.
@@ -199,6 +206,10 @@
PyErr_Format:char*:format::
PyErr_Format::...::
+PyErr_Warn:int:::
+PyErr_Warn:PyObject*:category:0 or +1:
+PyErr_Warn:char*:message::
+
PyEval_AcquireLock:void:::
PyEval_AcquireThread:void:::