I've been working on updating some old API-using code, and appear to have found some inconsistencies/misdocumented API calls. I was using 1.13, but these all seem to be present on the current documentation.

Reference Counting

PyArray_CastToType appears to steal the PyArray_Descr* object it is passed, but isn't documented as such. Many functions are documented as stealing this parameter, so not being there seems to imply that it won't. (I found this out the hard way whilst chasing reference count problems).

In fact, assuming that https://github.com/numpy/numpy/blob/master/numpy/core/code_generators/numpy_api.py is an accurate representation of the API, I looked over everything marked as stealing and there there are several other functions that steal but aren't documented as such:

• PyArray_FromScalar
• PyArray_GetField
• PyArray_SetField
• PyArray_CheckFromAny (though it says derived from PyArray_FromAny, which is documented as stealing the parameter, so perhaps this one doesn't count)
• PyArray_FromArray (same)
• PyArray_View
• PyArray_AsCArray (except the parameter listed is documented as an integer parameter?)
• PyArray_Zeros
• PyArray_Empty
• PyArray_SetUpdateIfCopyBase

(PyArray_EnsureAnyArray, PyArray_FromDimsAndDataAndDescr and PyArray_FromIter are listed as stealing, but don't appear to have documentation entries). I didn't double-check anything not listed as stealing.

Mislabelled parameters

PyArray_SIZE and PyArray_Size are labelled as both taking PyArrayObject*. However, my compiler appears to complain when PyArray_Size is used with such - needing to be cast to a PyObject* first.

If these are just missing I'm happy to update the documentation myself to add the "This function steals a reference to x" text to each function, but I'm new to the numpy code and some of the structure confuses me, so I'm not completely certain it's me that is incorrect, or if the documentation is correct but the implementation wrong (in which case, I suspect there's nothing to do but make the documentation match...)