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)