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)