[Numpy-discussion] Some problems with Numeric documenation

[Edward C. Jones]

Here are some documentation problems with Numeric (20.2.0). I use the html
form of the documentation.

1. descr->elsize is not documented.

2. The documentation for PyArray_FromDimsAndData says

       This function should only be used to access global data that will
       never be freed (like FORTRAN common blocks).

   The document writer copied this from the source code internal
   documentation.  As far as I can tell, this is wrong. I suggest

       The object returned by this function contains a pointer to a
       pre-existing block of data. If you delete the data before the
       Python reference count has dropped to zero, you will have a dangling
       pointer which is usually a disaster. One safe way to do this is to
       Py_DECREF the object in the same C function where it was created.

3. By a semi-automated application of grep and Python, I have found the
   following functions which appear to be in the C API and are not
   documented. Note that PyArray_FromDimsAndData and PyArray_CopyArray
   can be combined to do the C level equivalent of
       arr[a:b,c:d] = something

  PyArray_ArgMax
       multiarraymodule.c:extern PyObject *PyArray_ArgMax(PyObject *op) {
   PyArray_ArgSort
       multiarraymodule.c:extern PyObject *PyArray_ArgSort(PyObject *op) {
   PyArray_BinarySearch
       multiarraymodule.c:extern PyObject *PyArray_BinarySearch(PyObject *op1, PyObject *op2) {
   PyArray_CONTIGUOUS
       arrayobject.c:#define PyArray_CONTIGUOUS(m) (ISCONTIGUOUS(m) ? Py_INCREF(m), m : \
   PyArray_Choose
       multiarraymodule.c:extern PyObject *PyArray_Choose(PyObject *ip, PyObject *op) {
   PyArray_Concatenate
       multiarraymodule.c:extern PyObject *PyArray_Concatenate(PyObject *op) {
   PyArray_Converter
       arrayobject.c:extern int PyArray_Converter(PyObject *object, PyObject **address) {
   PyArray_CopyArray
       arrayobject.c:int PyArray_CopyArray(PyArrayObject *dest, PyArrayObject *src) {
   PyArray_CopyObject
       arrayobject.c:int PyArray_CopyObject(PyArrayObject *dest, PyObject *src_object) {
   PyArray_Correlate
       multiarraymodule.c:extern PyObject *PyArray_Correlate(PyObject *op1, PyObject *op2, int mode) {
   PyArray_FromDimsAndDataAndDescr
       arrayobject.c:PyObject *PyArray_FromDimsAndDataAndDescr(int nd, int *d, 
   PyArray_FromScalar
       arrayobject.c:PyObject *PyArray_FromScalar(PyObject *op, int type) {
   PyArray_InnerProduct
       multiarraymodule.c:extern PyObject *PyArray_InnerProduct(PyObject *op1, PyObject *op2) {
   PyArray_Item
       arrayobject.c:extern PyObject * PyArray_Item(PyObject *op, int i) {
   PyArray_NBYTES
       arrayobject.h:#define PyArray_NBYTES(mp) ((mp)->descr->elsize * PyArray_SIZE(mp))
   PyArray_Put
       arrayobject.c:extern PyObject *PyArray_Put(PyObject *self0, PyObject *indices0, 
   PyArray_PutMask
       arrayobject.c:extern PyObject *PyArray_PutMask(PyObject *self0, PyObject *mask0, 
   PyArray_Repeat
       multiarraymodule.c:extern PyObject *PyArray_Repeat(PyObject *aop, PyObject *op, int axis) {
   PyArray_Resize
       arrayobject.c:static PyObject * PyArray_Resize(PyArrayObject *self, PyObject *shape) {
   PyArray_Sort
       multiarraymodule.c:extern PyObject *PyArray_Sort(PyObject *op) {
   PyArray_TYPES
       arrayobject.h:enum PyArray_TYPES { PyArray_CHAR, PyArray_UBYTE, PyArray_SBYTE,
   PyArray_ToList
       arrayobject.c:static PyObject *PyArray_ToList(PyObject *self) {
   PyArray_Transpose
       multiarraymodule.c:extern PyObject *PyArray_Transpose(PyArrayObject *ap, PyObject *op) {
   PyArray_compare_lists
       arrayobject.c:extern int _PyArray_compare_lists(int *l1, int *l2, int n) {



       arrayobject.c:extern int _PyArray_compare_lists(int *l1, int *l2, int n) {

       multiarraymodule.c:extern PyObject *PyArray_Sort(PyObject *op) {