扭曲的文档字符串中这些格式的含义是什么？

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 producer ?

顺便问一下，这些格式是标准 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 本身生成文档，使用 epydoc twisted，但 epydoc 不了解 Zope 接口，因此不会自动将类链接到它们实现的接口。

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