Docstring format for input numpy arrays with mandatory datatype and dimensions

Question

For the sake of example, assume that I have a function that takes two numpy arrays as input parameters. The first array must be 2-dimensional and contain only floats. The second array must be 1-dimensional and contain only booleans.

Thus far I haven't really been able to find an existing convention for specifying input array datatype and dimensions in the docstring. One possible format (taking numpy docstring conventions as a basis) that I thought of was this:

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 a 'correct' docstring format? (i.e. does it not break any rules of existing docstring conventions?)

Answer 1

Dimension and item types are extra information about your arrays which are function arguments. Thus based on documentation you need a style like follows:

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

Which in this case should be like:

"""
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 you better to describe the data types and dimensions in your function description part as well.