python - Twisted 的文档字符串中这些格式的含义是什么？

Question

在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 文档字符串格式的一部分吗？如果是这样，我应该引用哪里？谢谢:)

Answer 1

Twisted 使用的文档格式是Epytext, which is documented on epydoc.sourceforge.net .

L{} 表示“链接”(即“这是一个 Python 标识符，请链接到它”) C{} 表示“代码”(即 hello C{foo} bar 的格式应类似于“hello foo bar”)。 I{} 仅表示“斜体”。您可以在 epytext 文档中看到更多字段。

Twisted 项目使用 pydoctor 生成文档，使用像 pydoctor --add-package twisted 这样的调用。它还有更多功能，可以生成指向 Twisted 所依赖的其他几个项目的链接，但是如果您想为 Twisted 贡献文档字符串，您可以使用它来获得灵感。您还可以使用 epydoc twisted 使用 epydoc 本身生成文档，但 epydoc 不知道 Zope 接口(interface)，因此不会自动将类链接到它们实现的接口(interface)。

The generated API documentation for each release is published on twistedmatrix.com ，您可以在那里浏览它。