摘要

命名的 Python 对象，例如模块、类和函数，都带有一个名为 __doc__ 的字符串属性。如果定义中的第一个表达式是字符串字面量，那么该字符串将被赋值给 __doc__ 属性。

__doc__ 属性被称为文档字符串，或 docstring。它通常用于总结模块、类或函数的接口。然而，由于文档字符串没有通用格式，用于提取 docstring 并将其转换为标准格式（例如 DocBook）文档的工具并未大量涌现，而现有的大部分工具都未被维护和使用。

Perl 文档

在 Perl 中，大多数模块都以一种名为 POD (Plain Old Documentation) 的格式进行文档编写。这是一种易于输入、非常低级的格式，与 Perl 解析器很好地集成。存在许多工具可以将 POD 文档转换为其他格式：信息、HTML 和手册页等。然而，在 Perl 中，这些信息在运行时不可用。

Java 文档

在 Java 中，类和函数前的特殊注释用于记录代码。一个用于提取这些注释并将其转换为 HTML 文档的程序叫做 javadoc，它是标准 Java 发行版的一部分。然而，唯一支持的输出格式是 HTML，而且 JavaDoc 与 HTML 有着非常密切的关系。

Python Docstring 目标

Python 文档字符串在解析时很容易被识别，并且也可用于运行时解释器。这种双重目的有时会带来一些问题：例如，有些人不愿意编写过长的 docstring，因为他们不希望在运行时占用太多空间。此外，由于目前缺乏工具，人们通过“打印”对象 docstring 来阅读它们，因此出现了一种将其保持简短且不含标记的趋势。这种趋势阻碍了编写更好的文档提取工具，因为它导致 docstring 包含的信息很少，难以解析。

高级解决方案

为了反驳字符串占用运行程序空间的异议，建议文档提取工具将出现在定义开头的字符串字面量的最大前缀连接起来。这些字符串中的第一个也将可在交互式解释器中使用，因此它应包含几行摘要。

Docstring 格式目标

这些是 docstring 格式的目标，正如在 doc-sig 中反复讨论的那样。

1. 它必须易于使用任何标准文本编辑器输入。
2. 它必须对普通观察者来说易于阅读。
3. 它不得包含可以从解析模块中推导出的信息。
4. 它必须包含足够的信息，以便可以转换为任何合理的标记格式。
5. 必须可以在 docstring 中编写模块的完整文档，而不会觉得受标记语言的限制。

Docstring 内容

对于上述第 5 条要求，需要指定 docstring 中必须包含哪些内容。

至少必须提供以下内容

1. 一个表示“这是一个 Python *某物*，猜猜是什么”的标签

   示例：在“POP3 类”这句话中，我们需要以这种方式标记“POP3”。解析器将能够从 poplib 模块的内容中猜测它是一个类，但我们需要让它猜测。

2. 表示“这是一个 Python 类/模块/类变量/实例变量…”的标签

   示例：Python 中单例类 A 的常用惯例是，将 _A 作为类，而 A 是一个返回 _A 对象的函数。尽管如此，通常仍将该类记录为 A。这需要有能力说“类 A”，并且将 A 超链接并标记为类。

3. 一种方便地包含 Python 源代码/Python 交互式会话的方式
4. 强调/加粗
5. 列表/表格

Docstring 基本结构

文档字符串将采用 StructuredTextNG 格式（http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG）。由于 StructuredText 尚不足以处理上述 (a) 和 (b) 两点，我们需要对其进行扩展。我建议使用 [<可选描述>:python 标识符]。例如：[class:POP3]、[:POP3.list] 等。如果描述缺失，将根据文本进行猜测。

未解决的问题

在 ST 中是否有转义字符的方法？如果有，怎么做？（例如：行首的 * 不作为列表符号）

我上面关于 Python 符号的建议是否与 ST-NG 兼容？扩展 ST-NG 以支持它有多难？

我们如何描述函数的输入和输出类型？

我们对每个 docstring（模块/类/函数）强制执行哪些额外的限制？

猜测器规则是什么？

被拒绝的建议

XML – 它非常难以输入，而且过于杂乱，无法舒适地阅读。