具有必需数据类型和维度的输入numpy数组的Docstring格式

Question

为了举例，假设我有一个函数，它将两个numpy数组作为输入参数。第一个数组必须是2维的，并且只包含浮点数。第二个数组必须是1维的，只包含布尔值。

到目前为止，我还没有找到在docstring中指定输入数组数据类型和维度的现有约定。一种可能的格式（以numpy docstring约定为基础）我想到的是：

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.

   """

这可以被视为正确的＆＃39; docstring格式？ （即它是否违反了现有文档字符串约定的任何规则？）

Answer 1

维度和项目类型是有关作为函数参数的数组的额外信息。因此，根据文档，您需要一个如下样式：

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

在这种情况下应该是这样的：

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

请注意，如果您想进行更多说明，最好还是在功能描述部分中描述数据类型和尺寸。