PEP 216 – 文档字符串格式

重要

此 PEP 已被撤回。

它已被 PEP 287 取代。

抽象

命名的 Python 对象（如模块、类和函数）具有 字符串属性称为 。如果里面的第一个表达式 定义是一个文本字符串，该字符串是分配的 添加到属性中。__doc____doc__

该属性称为文档字符串或文档字符串。 它通常用于总结模块、类或 功能。但是，由于文档没有通用格式 字符串，用于提取文档字符串并将其转换为 标准格式的文档（例如，DocBook）尚未出现 大量增加，而那些确实存在的大部分都是 未维护和未使用。__doc__

Perl 文档

在 Perl 中，大多数模块都以一种称为 POD – PlAIn 的格式记录 旧文档。这是一种易于输入的非常低级的格式 它与 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 的东西，你猜怎么着”

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

2. 表示“这是一个 Python 类/模块/类 var/instance var...”的标签

   示例：单例类的常用 Python 习语是 have as the class，以及返回对象的函数。这很平常 尽管如此，将类记录为 .这需要 力量说“班级”，并有超链接和标记 作为一个类。A_AA_AAAA

3. 包含 Python 源代码/Python 交互会话的简单方法

4. 强调/粗体

5. 列表/表格

Docstring 基本结构

由于 StructuredText 还不够强大，无法处理 （a） 和 （b） 上面，我们将需要扩展它。我建议使用 . 例如：、等。如果缺少描述， 将从文本中做出猜测。[<optional description>:python identifier][class:POP3][:POP3.list]

未解决的问题

有没有办法在ST中转义字符？如果是这样，如何？ （例如：* 在行的开头，而不是项目符号）

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

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

我们对每个文档字符串强制执行哪些附加约束？ （模块/类/函数）？

猜测者规则是什么？

被拒绝的建议

XML – 打字非常困难，而且太杂乱，无法舒适地阅读。

The End