如何为以下 Python 函数编写文档字符串?
How do I write a docstring for the following Python function?
假设我有以下功能:
def get_matrix(*args, arbitrary=True):
if arbitrary == True:
return np.random.randint(-10,10, size=[args[0],args[1]])
else:
return np.array(args[0])
所以函数
- 生成矩阵(如果任意== True);在这种情况下,它需要两个 int 参数。
或
- 将数组(如果任意 == False)(由元组或列表表示)转换为 numpy 的数组
如何为此函数编写简洁易读的文档字符串? (最好保留 numpy's docstring style)Numpy 没有关于如何记录 *args 和 **kwargs 的任何内容。 (或者也许他们找到了,但到目前为止我还没有找到任何东西)
任何对您的项目有意义的东西。 *args
的通用术语是 "positional arguments",通常您会希望将它们单独称为 "the n
th positional argument"。关键字参数 **kwargs
通常应根据具体情况分别使用可接受的键和值单独提及,除非您方法中的 kwargs 正在充当其他人方法中的 kwargs 的代理,在这种情况下您可以也只写 "Keyword arguments are the same as [other method], see that documentation for more details".
你给出的例子在这种情况下很难,主要是因为这是一种不好的做法——一个方法应该做一件事;如果你有一个方法根据标志的值做两件不同的事情,那么为什么不只拥有两个方法并让调用者显式调用其中一个呢? (进一步阅读:PEP 20)
Numpy 的文档标准似乎走得更远,通常完全避开通用 **kwargs
(支持显式命名的关键字),并且更喜欢可以在文档字符串中引用的命名位置参数。您链接的文档没有提供关于该主题的明确建议,但我倾向于 *args
作为 'variable name' (保留星号以表示它们是位置参数)和 integers
作为值(注意复数),然后在描述中明确指出它代表位置参数。或者,我在下面所做的只是明确地将其列为 "positional arguments" (毕竟,这种文档字符串格式无论如何对类型提示都没有用)。
这主要是个人喜好,但我会这样记录您的功能:
def get_matrix(*args, arbitrary=True):
"""
If `arbitrary` is True (default), generates a random matrix,
with x and y bounds represented by the first two given
positional args, and returns it.
If `arbitrary` is False, then instead coerces the first positional
argument into a np.array, and returns that.
parameters
----------
positional args: ints
purpose depends on the value of arbitrary (see above)
arbitrary: bool
determines the behavior of the function (see above)
returns
-------
if arbitrary is true, a random 2D array of defined size.
otherwise, the first positional argument coerced to a np.array
"""
if arbitrary == True:
return np.random.randint(-10,10, size=[args[0],args[1]])
else:
return np.array(args[0])
假设我有以下功能:
def get_matrix(*args, arbitrary=True):
if arbitrary == True:
return np.random.randint(-10,10, size=[args[0],args[1]])
else:
return np.array(args[0])
所以函数
- 生成矩阵(如果任意== True);在这种情况下,它需要两个 int 参数。
或
- 将数组(如果任意 == False)(由元组或列表表示)转换为 numpy 的数组
如何为此函数编写简洁易读的文档字符串? (最好保留 numpy's docstring style)Numpy 没有关于如何记录 *args 和 **kwargs 的任何内容。 (或者也许他们找到了,但到目前为止我还没有找到任何东西)
任何对您的项目有意义的东西。 *args
的通用术语是 "positional arguments",通常您会希望将它们单独称为 "the n
th positional argument"。关键字参数 **kwargs
通常应根据具体情况分别使用可接受的键和值单独提及,除非您方法中的 kwargs 正在充当其他人方法中的 kwargs 的代理,在这种情况下您可以也只写 "Keyword arguments are the same as [other method], see that documentation for more details".
你给出的例子在这种情况下很难,主要是因为这是一种不好的做法——一个方法应该做一件事;如果你有一个方法根据标志的值做两件不同的事情,那么为什么不只拥有两个方法并让调用者显式调用其中一个呢? (进一步阅读:PEP 20)
Numpy 的文档标准似乎走得更远,通常完全避开通用 **kwargs
(支持显式命名的关键字),并且更喜欢可以在文档字符串中引用的命名位置参数。您链接的文档没有提供关于该主题的明确建议,但我倾向于 *args
作为 'variable name' (保留星号以表示它们是位置参数)和 integers
作为值(注意复数),然后在描述中明确指出它代表位置参数。或者,我在下面所做的只是明确地将其列为 "positional arguments" (毕竟,这种文档字符串格式无论如何对类型提示都没有用)。
这主要是个人喜好,但我会这样记录您的功能:
def get_matrix(*args, arbitrary=True):
"""
If `arbitrary` is True (default), generates a random matrix,
with x and y bounds represented by the first two given
positional args, and returns it.
If `arbitrary` is False, then instead coerces the first positional
argument into a np.array, and returns that.
parameters
----------
positional args: ints
purpose depends on the value of arbitrary (see above)
arbitrary: bool
determines the behavior of the function (see above)
returns
-------
if arbitrary is true, a random 2D array of defined size.
otherwise, the first positional argument coerced to a np.array
"""
if arbitrary == True:
return np.random.randint(-10,10, size=[args[0],args[1]])
else:
return np.array(args[0])