DOC: Correct selected C docstrings to eliminate warnings (numpy#27497)

Addresses numpy#27377, eliminating all C docstring warning messages.

This is a minimal set of changes, simply eliminating the observed warning messages, with no attempt to improve C docstring content overall, per advice of @mattip.

Reviewers,

Some changes were straightforward:
-- The name of the @param variable to be documented was missing. I inserted it.
-- The name of the @param variable was misspelled. I corrected it.
-- An @param line documented a variable that no longer existed or had been split into two. I made the obvious fix.
-- In one case, I removed a docstring from an .h file that simply duplicated the docstring in the corresponding .c file.

The changes to pay more attention to are those where I had to supply missing Description text. For those, I simply took my best shot and used as few words as I could, figuring the less I wrote, the fewer things would be said incorrectly.
To verify the error messages were being eliminated, I used the same commands as were documented in the original issue but piped the sorted, unique warnings to a file which I diffed against the original list as I worked.
$ CC=clang CXX=clang++ CFLAGS=-Wdocumentation pip install --log PIP.log .
$ grep -- -Wdocumentation PIP.log | sed -E -e 's/^\S+\s+//' | sort -n | uniq > warnings.list

Some fixup/suggestions contributed by Sebastian

Co-authored-by: Sebastian Berg <[email protected]>

Author: eagunn

numpy/_core/include/numpy/dtype_api.h

@@ -268,7 +268,8 @@ typedef int (PyArrayMethod_TranslateGivenDescriptors)(int nin, int nout,
  *
  * The function must clean up on error.
  *
- * @param nargs Number of arguments
+ * @param nin Number of input arguments
+ * @param nout Number of output arguments
  * @param new_dtypes The DTypes of the output (usually probably not needed)
  * @param given_descrs Original given_descrs to the resolver, necessary to
  *        fetch any information related to the new dtypes from the original.

numpy/_core/src/common/npy_argparse.c

@@ -280,11 +280,11 @@ raise_missing_argument(const char *funcname,
  *
  * See macro version for an example pattern of how to use this function.
  *
- * @param funcname
- * @param cache
+ * @param funcname Function name
+ * @param cache a NULL initialized persistent storage for data
  * @param args Python passed args (METH_FASTCALL)
- * @param len_args
- * @param kwnames
+ * @param len_args Number of arguments (not flagged)
+ * @param kwnames Tuple as passed by METH_FASTCALL or NULL.
  * @param ... List of arguments (see macro version).
  *
  * @return Returns 0 on success and -1 on failure.

numpy/_core/src/common/npy_argparse.h

@@ -69,7 +69,7 @@ NPY_NO_EXPORT int init_argparse_mutex(void);
  * used in cunjunction with the macro defined in the same scope.
  * (No two `npy_parse_arguments` may share a single `NPY_PREPARE_ARGPARSER`.)
  *
- * @param funcname
+ * @param funcname Function name
  * @param args Python passed args (METH_FASTCALL)
  * @param len_args Number of arguments (not flagged)
  * @param kwnames Tuple as passed by METH_FASTCALL or NULL.

numpy/_core/src/common/npy_import.h

@@ -81,7 +81,7 @@ npy_import(const char *module, const char *attr)
  *
  * @param module Absolute module name.
  * @param attr module attribute to cache.
- * @param cache Storage location for imported function.
+ * @param obj Storage location for imported function.
  */
 static inline int
 npy_cache_import_runtime(const char *module, const char *attr, PyObject **obj) {

numpy/_core/src/multiarray/array_coercion.c

@@ -660,8 +660,8 @@ npy_new_coercion_cache(
 /**
  * Unlink coercion cache item.
  *
- * @param current
- * @return next coercion cache object (or NULL)
+ * @param current This coercion cache object
+ * @return next Next coercion cache object (or NULL)
  */
 NPY_NO_EXPORT coercion_cache_obj *
 npy_unlink_coercion_cache(coercion_cache_obj *current)
@@ -905,7 +905,7 @@ find_descriptor_from_array(
  * it supports inspecting the elements when the array has object dtype
  * (and the given datatype describes a parametric DType class).
  *
- * @param arr
+ * @param arr The array object.
  * @param dtype NULL or a dtype class
  * @param descr A dtype instance, if the dtype is NULL the dtype class is
  *              found and e.g. "S0" is converted to denote only String.

numpy/_core/src/multiarray/array_method.c

@@ -123,15 +123,16 @@ is_contiguous(
  * true, i.e., for cast safety "no-cast". It will not recognize view as an
  * option for other casts (e.g., viewing '>i8' as '>i4' with an offset of 4).
  *
- * @param context
- * @param aligned
- * @param move_references UNUSED.
- * @param strides
- * @param descriptors
- * @param out_loop
- * @param out_transferdata
- * @param flags
- * @return 0 on success -1 on failure.
+ * @param context The arraymethod context
+ * @param aligned Flag indicating data is aligned (1) or not (0)
+ * param move_references UNUSED -- listed below but doxygen doesn't see as a parameter
+ * @param strides Array of step sizes for each dimension of the arrays involved
+ * @param out_loop Output pointer to the function that will perform the strided loop.
+ * @param out_transferdata Output pointer to auxiliary data (if any) 
+ *        needed by the out_loop function.
+ * @param flags Output pointer to additional flags (if any) 
+ *        needed by the out_loop function
+ * @returns 0 on success -1 on failure.
  */
 NPY_NO_EXPORT int
 npy_default_get_strided_loop(
@@ -169,7 +170,7 @@ npy_default_get_strided_loop(
 /**
  * Validate that the input is usable to create a new ArrayMethod.
  *
- * @param spec
+ * @param spec Array method specification to be validated
  * @return 0 on success -1 on error.
  */
 static int

numpy/_core/src/multiarray/common.c

@@ -188,9 +188,9 @@ _IsWriteable(PyArrayObject *ap)
 /**
  * Convert an array shape to a string such as "(1, 2)".
  *
- * @param Dimensionality of the shape
- * @param npy_intp pointer to shape array
- * @param String to append after the shape `(1, 2)%s`.
+ * @param n Dimensionality of the shape
+ * @param vals npy_intp pointer to shape array
+ * @param ending String to append after the shape `(1, 2)%s`.
  *
  * @return Python unicode string
  */
@@ -299,12 +299,11 @@ dot_alignment_error(PyArrayObject *a, int i, PyArrayObject *b, int j)
 /**
  * unpack tuple of PyDataType_FIELDS(dtype) (descr, offset, title[not-needed])
  *
- * @param "value" should be the tuple.
+ * @param value should be the tuple.
+ * @param descr will be set to the field's dtype
+ * @param offset will be set to the field's offset
  *
- * @return "descr" will be set to the field's dtype
- * @return "offset" will be set to the field's offset
- *
- * returns -1 on failure, 0 on success.
+ * @return -1 on failure, 0 on success.
  */
 NPY_NO_EXPORT int
 _unpack_field(PyObject *value, PyArray_Descr **descr, npy_intp *offset)

numpy/_core/src/multiarray/common.h

@@ -71,13 +71,6 @@ dot_alignment_error(PyArrayObject *a, int i, PyArrayObject *b, int j);
 
 /**
  * unpack tuple of PyDataType_FIELDS(dtype) (descr, offset, title[not-needed])
- *
- * @param "value" should be the tuple.
- *
- * @return "descr" will be set to the field's dtype
- * @return "offset" will be set to the field's offset
- *
- * returns -1 on failure, 0 on success.
  */
 NPY_NO_EXPORT int
 _unpack_field(PyObject *value, PyArray_Descr **descr, npy_intp *offset);

numpy/_core/src/multiarray/common_dtype.c

@@ -106,7 +106,7 @@ PyArray_CommonDType(PyArray_DTypeMeta *dtype1, PyArray_DTypeMeta *dtype2)
  * default_builtin_common_dtype
  *
  * @param length Number of DTypes
- * @param dtypes
+ * @param dtypes List of DTypes to be reduced
  */
 static PyArray_DTypeMeta *
 reduce_dtypes_to_most_knowledgeable(

numpy/_core/src/multiarray/conversion_utils.c

@@ -1123,7 +1123,7 @@ PyArray_IntpFromPyIntConverter(PyObject *o, npy_intp *val)
  * @param  seq      A sequence created using `PySequence_Fast`.
  * @param  vals     Array used to store dimensions (must be large enough to
  *                      hold `maxvals` values).
- * @param  max_vals Maximum number of dimensions that can be written into `vals`.
+ * @param  maxvals  Maximum number of dimensions that can be written into `vals`.
  * @return          Number of dimensions or -1 if an error occurred.
  *
  * .. note::