9

在 twisted 的源代码中，许多文档字符串包含这样的格式：L{xxx} 或 C{xxx} 或以“@”开头的行，它们的含义是什么？

例如，在 twisted/internet/interfaces.py 中：

def registerProducer(producer, streaming):
    """
    Register to receive data from a producer.
    ...
    For L{IPullProducer} providers, C{resumeProducing} will be called once
    each time data is required.
    ...
    @type producer: L{IProducer} provider
    ...
    @return: C{None}
    """

L{IPullProducer}、C{resumeProducing}、@type 生产者？

顺便说一句，这些格式是标准 python 文档字符串格式的一部分吗？如果是这样，我应该参考哪里？谢谢 ：）

4

1 回答 1

12

Twisted 使用的文档格式是Epytext，记录在epydoc.sourceforge.net.

L{}表示“链接”（即“这是一个 Python 标识符，请链接到它”）C{}表示“代码”（即hello C{foo} bar应该格式化为“hello foobar”）。 I{}只是意味着“斜体”。您可以在 epytext 文档中看到更多字段。

Twisted 项目使用pydoctor生成其文档，使用类似pydoctor --add-package twisted. 它还有更多内容，可以生成指向 Twisted 所依赖的其他几个项目的链接，但如果你想向 Twisted 贡献文档字符串，你可以使用它来获得一个想法。您也可以使用 epydoc 本身生成文档epydoc twisted，但是 epydoc 不了解 Zope 接口，因此不会自动将类链接到它们实现的接口。

每个版本生成的 API 文档都发布在 twistedmatrix.com 上，您可以在那里浏览。

于 2012-06-17T08:09:09.480 回答