PEP 216 – 文档字符串格式

猫勺猫勺 05-04 81 阅读 0 评论

重要

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 微信扫一扫

文章声明:以上内容(如有图片或视频在内)除非注明,否则均为腾龙猫勺儿原创文章,转载或复制请以超链接形式并注明出处。

本文作者:猫勺本文链接:https://www.jo6.cn/post/97.html

上一篇 下一篇

相关阅读

发表评论

访客 访客
快捷回复: 表情:
评论列表 (暂无评论,81人围观)

还没有评论,来说两句吧...

取消
微信二维码
微信二维码
支付宝二维码