python 文档字符串标准_Spyder docstrings文档字符串的标准

Spyder docstrings文档字符串的规范

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

特点和标准

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

docstrings需要遵守的标准:

无缩进的下划线被用来做分割线

不同的缩进量, 表示不同的文本块. 就像python代码一样, 严格坚守缩进和排齐的原则.

函数的docstring应该放置在函数体内的第一行.

通常包括: 功能, 参数, 返回值, 举例说明等4个小标题

">>> "前缀的行 表示源代码行, 经常用在"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)