Question

In twisted’s sourcecode, many docstrings contain formats like this: L{xxx} or C{xxx} or a line begin with an ‘@’, what’s their meanings?

for example, in 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 ?

By the way, are these formats a part of standard python docstring formats? If so, where should I refer to? Thanks 🙂

Answer 1

The documentation format used by Twisted is Epytext, which is documented on epydoc.sourceforge.net.

L{} means “link” (i.e. “this is a Python identifier, please link to it”) C{} means “code” (i.e. hello C{foo} bar should be formatted like “hello foo bar”). I{} just means “in italics”. You can see more fields in the epytext documentation.

The Twisted project generates its documentation with pydoctor, using an invocation like pydoctor --add-package twisted. There’s a little more to it, to generate links to a couple of other projects that Twisted relies upon, but you can use that to get an idea if you want to contribute docstrings to Twisted. You can also generate the documentation with epydoc itself, using epydoc twisted, but epydoc doesn’t know about Zope Interface and so won’t automatically link classes to the interfaces that they implement.

The generated API documentation for each release is published on twistedmatrix.com, and you can browse it there.