Spyder docstrings文档字符串的标准

Spyder docstrings文档字符串的规范

python的docstring 非常重要. 有时候编写一个小函数只需要几行代码就可了. 但是完善的文档很可能比源代码长许多.

特点和标准

docstrings的特点: 可重构的结构化的文档字符串.

docstrings需要遵守的标准:

1. 无缩进的下划线被用来做分割线
2. 不同的缩进量, 表示不同的文本块. 就像python代码一样, 严格坚守缩进和排齐的原则.
3. 函数的docstring应该放置在函数体内的第一行.
4. 通常包括: 功能, 参数, 返回值, 举例说明等4个小标题
5. ">>> "前缀的行 表示源代码行, 经常用在"Example:"标题里.

在对象查看器(object inspector)里的身姿:

源码举例:

def DMA(p,f):
    u'''
    功能:
    ------
      计算加权移动均值
    输入参数:
    -------
      p: ndarray类型
        输入数据, 比如价格, 成交量等
      f: ndarray类型,
        加权因子, 比如换手率: vol/sum(vol, 60). Spyder is a powerful interactive
        development environment for the Python language
        with advanced editing, interactive testing, debugging and ...
    返回值:
    -------
      ndarray类型
        DMA均值
    备注:
    ----
      docstring标准: 可重构的结构化的文档字符串.
        1. 无缩进的下划线被用来做分割线
        2. 不同的缩进量, 表示不同的文本块. 就像python代码一样, 严格坚守缩进和排齐的原则.

    '''
    y=[0]*len(p)
    for i in np.arange(len(p)):
        if i==0:
            y[i] = p[i]
        else:
            y[i] = f[i]*p[i] + (1-f[i])*y[i-1]
    return np.array(y)