18.1 为help()函数编写docstrings

Python为我们提供了许多地方可以编写文档。包、模块、类或者函数的定义中都包含一个描述被定义对象的字符串。在本书中，我们没有在任何例子中使用文档注释（docstrings），因为我们主要关注Python的编程细节，而不是需要交付的、完整的软件产品。

当我们开始学习高级面向对象设计技术并且关注整个可交付的产品时，文档注释就成为可交付产品中的一个重要部分了。文档注释可以为我们提供一些重要的信息。

• API：参数、返回值和抛出的异常。
• 对预期行为的描述。
• 可选的，提供doctest的测试结果。更多关于测试的信息，参见第15章“可测试性的设计”。

当然，我们可以在文档注释中包括更多的信息。我们可以提供关于设计、架构和需求的更多细节。在某些时候，这些更抽象、高级的问题和Python代码没有直接关系。这种高级设计和需求不属于代码或者文档注释。

help()函数提取并显示文档注释，它会对文本执行一些基本的格式化操作。help()函数通过site包安装在交互式Python环境中。这个功能实际上是定义在pydoc包中的。大体上，我们可以通过导入并且扩展这个包来自定义help()的输出。

编写适合help()的文档相对简单。下面是help(round)的一个典型输出。

round(…)
　　round(number[, ndigits]) -> number

　　Round a number to a given precision in decimal digits (default 0
digits).
　　This returns an int when called with one argument, otherwise the
　　same type as the number. ndigits may be negative.

这段代码展示了编写文档所有必要的元素：总结、API和描述。API和总结在第1行：function( parameters ) -> results。

描述文本定义了函数的功能。更复杂的函数可能会对异常或者对这个函数非常重要的、唯一的边界情况进行描述。例如，round()函数没有描述细节、可能抛出的TypeError。

一个面向help()的文档注释应该是不带有任何标记的纯文本。我们添加一些RST标记，但是help()不会使用这些标记。

我们只需要提供文档注释，help()就会开始工作。由于这种做法非常简单，因此没有任何原因不这么做。每个函数和类都需要一些文档注释，这样help()就可以显示一些有用的信息。