twisted的docstring中这些格式的含义是什么？

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,记录在案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上,您可以在那里浏览它.