Docstring format for inputting numpy arrays with required data type and sizes

Question

For example, suppose I have a function that takes two numpy arrays as input parameters. The first array must be two-dimensional and contain only floats. The second array must be one-dimensional and contain only Booleans.

So far, I really have not been able to find an existing convention for specifying the data type and size of the input arrays in docstring. One of the possible formats (with the adoption of numpy docstring conventions as the basis), which I thought of, was as follows:

def example_function(arr1, arr2): """This is an example function. Parameters ---------- arr1 : ndarray(dtype=float, ndim=2) Array containing some kind of data. arr2 : ndarray(dtype=bool, ndim=1) Array containing some kind of mask. """ 

Can this be considered the "correct" docstring format? (i.e. doesn’t it violate any rules of existing docstring conventions?)

Answer 1

Element sizes and types are additional information about your arrays that are function arguments. Thus, based on the documentation, you will need the following style:

 """ x : type Description of parameter `x`. """ 

What in this case should be as follows:

 """ Parameters ---------- arr1 : ndarray 2D array containing data with `float` type. arr2 : ndarray 1D mask array(containing data with boolean type). """ 

And note that if you want to make more clarifications, it is better to describe the types and sizes of data in their part of the function description.