18.4 编写有效的文档字符串

当编写文档字符串时，我们需要考虑我们的受众需要的基本信息是什么。当我们介绍如何使用库模块时，我们需要知道什么？不管我们问什么问题，其他的程序员通常也会有同样的问题。当我们编写文档字符串时，不应该超过下面的两个边界。

• 最好避免抽象概述、高层需求、用户故事或者没有直接与代码相关的背景信息。我们应该让文档字符串专注于代码本身。我们应该在一个独立的文档中提供背景信息。类似Sphinx这样的工具可以将背景材料和代码合并到一个单独的文档中。
• 最好也避免过度详细地描述这个实现的工作细节。因为代码都是现成的，所以没有理由在文档中重复代码。如果代码写的太晦涩难懂，那么我们可能需要重写，把它写得更清晰一些。

开发者想知道的最重要的事情可能是一个关于如何使用Python对象的示例程序。使用RST标记::的文本块是这些示例的骨干。

我们通常会用下面的方式编写代码示例。

Here's an example::
　　d= Deck()
　　c= d.pop()

一个缩进块之前的双冒号::让这个缩进块被RST解析器识别为一段代码，并且会以文本的形式传递给最终的文档。

除了示例之外，正式的API描述也非常重要。我们会在后面的部分中介绍一些描述API定义的技术。这些技术都基于RST的字段清单（field list）语法。这种语法非常简单，这也让它非常灵活。

我们了解了如何编写示例和API之后，还会有一些其他因素需要考虑。我们还需要哪些其他元素依赖于上下文，大约有以下3种情况。

• 文件（包括包和模块）：在这些例子中，我们为一系列的模块、类或者函数提供了概览或介绍。我们需要在文件中提供一个简单的蓝图或者不同元素的概览。当模块相对比较小时，我们可以在这个级别上提供doctest和代码示例。
• 类（包括方法函数）：我们通常会在这里提供用于描述类API的代码实例和doctest块。由于类可能是有状态的而且可能包含相对复杂的API，因此我们可能需要提供更长的文档。独立的方法函数通常都会有详细的文档来描述它们。
• 函数：我们可以提供用于讲解函数的代码示例和doctest块。因为函数通常是没有状态的，所以我们可以包含一个相对简单的API描述。在一些情况下，我们可以避免更复杂的RST标记并且专注于help()函数的文档。

我们会介绍这些广泛的、模糊的文档上下文中的一些细节。