在 python 文档字符串中写入默认值的标准方法是什么？

【问题标题】：What is the standard way for writing default values in a python docstring?在 python 文档字符串中写入默认值的标准方法是什么？
【发布时间】：2016-01-19 17:09:15
【问题描述】：

我有一个参数设置为默认值的函数。我正在使用NumPy-style 文档字符串，但我在其他地方看到了默认值。在文档字符串中写“默认”的普遍接受的位置是什么？

def some_func(a_num=None, a_string=None):
    ''' A function that does something special.

    Parameters
    ==========
    a_num : int, default 100                        # is it written here?
        An important number.
    a_string : str, default 'foo'
        A useful string.  Default is 'foo'.         # or here?    
 
    '''

【问题讨论】：

标签： python numpy docstring

【解决方案1】：

如果您在链接的文档中进一步阅读，似乎没有一种标准样式：

可选关键字参数具有默认值，作为函数签名的一部分显示。它们也可以在描述中详细说明：
Description of parameter `x` (the default is -1, which implies summation
over all axes).
当一个参数只能采用一组固定值中的一个时，这些值可以用大括号列出，默认值首先出现：
order : {'C', 'F', 'A'}
    Description of `order`.

我建议为您自己的项目选择一种风格并坚持下去。

【讨论】：

我注意到了这一点。我想知道哪种风格更普遍。特别是不干扰常见文档字符串解析器的一种。