Docstring——RST标记和文档工具

所有的Python代码都应该在模块、类和方法级别包含docstrings。不是每个方法都需要docstring，有一些方法名已经很好了，不需要进一步说明。而大多数情况下，文档的说明是基本的。

Python文档通常使用ReStructured Text（RST）标记来写。

然而，在本书的示例代码中，为了限制本书内容在合理的范围内，没有使用docstrings。这样的缺点是，docstrings看起来是可选的，可它们是必需的。

再次强调，docstrings是必需的。

docstrings在Python中通过以下3种方式使用。

• 内部的help()函数用于显示docstrings。
• doctest工具可以在docstrings中查找示例并把它们当作测试用例运行。
• 类似Sphinx和epydoc这样的外部工具可以帮助文档的提取。

由于RST相对简单，编写好的docstrings相对非常简单。我们会在第18章“质量和文档”中对文档以及预计标记进行详细介绍。现在通过一个例子来看一下docstring的形式。

def factorial( n ):
　　"""Compute n! recursively.

　　:param n: an integer >= 0
　　:returns: n!

　　Because of Python's stack limitation, this won't
　　compute a value larger than about 1000!.

　　>>> factorial(5)
　　120
　　"""
　　if n == 0: return 1
　　return n*factorial(n-1)

以上代码展示了RST标记的参数和返回值，还包括了关于限制的一段说明。所包括的doctest输出可用于验证使用doctest工具完成的实现。有很多标记功能可用于提供更多的结构和语义方面的信息。