¿Qué significan estos formatos en docstring twisted?

Question

En el código fuente de twisted, muchas docstrings contienen formatos como este: L {xxx} o C {xxx} o una línea que comienza con '@', ¿cuál es su significado?

por ejemplo, en trenzado/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}, productor @type?

Por cierto, ¿estos formatos son parte de los formatos docstring estándar de python? Si es así, ¿a dónde debería referirme? Gracias :)

Answer 1

El formato de documentación utilizado por Twisted es Epytext, which is documented on epydoc.sourceforge.net.

L{} significa "link" (es decir, "se trata de un identificador de Python, satisfaga ligan a ella") C{} medios "código" (es decir hello C{foo} bar debe ser formateado como "hello foo bar"). I{} solo significa "en cursiva". Puede ver más campos en la documentación de epytext.

El proyecto Twisted genera su documentación con pydoctor, usando una invocación como pydoctor --add-package twisted. Hay algo más que eso, generar enlaces a un par de otros proyectos en los que Twisted confía, pero puedes usarlos para hacerte una idea si quieres contribuir con documentos en Twisted. También puede generar la documentación con epydoc, utilizando epydoc twisted, pero epydoc no conoce la interfaz Zope y por lo tanto no vinculará automáticamente las clases a las interfaces que implementen.

The generated API documentation for each release is published on twistedmatrix.com, y puedes buscarlo allí.