摘要

命名 Python 对象，例如模块、类和函数，都有一个名为 __doc__ 的字符串属性。如果定义中的第一个表达式是文字字符串，则该字符串将被分配给 __doc__ 属性。

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

Perl 文档

在 Perl 中，大多数模块都以称为 POD（简单旧文档）的格式进行文档化。这是一种易于键入的非常底层的格式，可以很好地与 Perl 解析器集成。许多工具可以将 POD 文档转换为其他格式：info、HTML 和手册页等。但是，在 Perl 中，这些信息在运行时不可用。

Java 文档

在 Java 中，类和函数之前的特殊注释用于为代码添加文档。一个用于提取这些注释并将其转换为 HTML 文档的程序被称为 javadoc，它是标准 Java 发行版的一部分。但是，支持的唯一输出格式是 HTML，而 JavaDoc 与 HTML 关系密切。

Python 文档字符串目标

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

高级解决方案

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

文档字符串格式目标

这些是文档字符串格式的目标，正如在 doc-sig 中反复讨论的那样。

1. 它必须使用任何标准文本编辑器易于键入。
2. 它必须对普通观察者来说可读。
3. 它不应包含可以通过解析模块推断出来的信息。
4. 它必须包含足够的信息，以便可以将其转换为任何合理的标记格式。
5. 必须能够在不受到标记语言限制的情况下，使用文档字符串编写模块的全部文档。

文档字符串内容

对于上述要求 5，需要指定文档字符串中必须包含的内容。

至少必须提供以下内容：

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

   示例：在句子“POP3 类”中，我们需要标记“POP3”。解析器将能够从 poplib 模块的内容中推断出它是一个类，但我们需要让它猜猜。

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

   示例：单例类 A 的常见 Python 习惯用法是使用 _A 作为类，而 A 则是一个返回 _A 对象的函数。尽管如此，通常还是要将该类记录为 A。这需要有力量说“类 A”，并将 A 作为类进行超链接和标记。

3. 一种简单的方法，用于包含 Python 源代码/Python 交互式会话
4. 强调/粗体
5. 列表/表格

文档字符串基本结构

文档字符串将使用 StructuredTextNG (http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG) 由于 StructuredText 还没有强大到足以处理上述 (a) 和 (b)，因此我们需要扩展它。我建议使用 [<optional description>:python identifier]。例如：[class:POP3]、[:POP3.list] 等。如果描述缺失，则将根据文本进行推断。

未解决的问题

有没有办法在 ST 中转义字符？如果有，如何操作？（示例：一行开头的 * 而不使其成为项目符号）

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

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

我们对每个文档字符串施加什么附加约束？（模块/类/函数）？

推断规则是什么？

被拒绝的建议

XML – 键入起来很困难，而且过于杂乱，难以舒适地阅读。