Was bedeuten diese Formate im Docstring von twisted?

Question

Im Quellcode von twisted enthalten viele Docstrings folgende Formate: L {xxx} oder C {xxx} oder eine Zeile beginnt mit einem '@', was bedeuten sie?

zum Beispiel in der verdrehten/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 Produzent?

Sind diese Formate übrigens Teil von Standard-Python-Docstring-Formaten? Wenn ja, wo soll ich mich beziehen? Danke :)

Answer 1

Das von Twisted verwendete Dokumentationsformat ist Epytext, which is documented on epydoc.sourceforge.net.

L{} bedeutet "link" (das heißt "Dies ist ein Python Kennung, bittet es link") C{} Mittel "Code" (d.h. hello C{foo} bar sollte wie "Hallo foo bar" formatiert werden). I{} bedeutet nur "in Kursivschrift". Sie können mehr Felder in der epytext Dokumentation sehen. Das Twisted-Projekt generiert seine Dokumentation mit pydoctor unter Verwendung eines Aufrufs wie pydoctor --add-package twisted. Es gibt ein wenig mehr, um Links zu anderen Projekten zu generieren, auf die Twisted angewiesen ist, aber Sie können damit eine Idee bekommen, wenn Sie Docstrings zu Twisted beitragen möchten. Sie können die Dokumentation auch mit epydoc selbst erzeugen, indem Sie epydoc twisted verwenden, aber epydoc weiß nichts über Zope Interface und verbindet daher die Klassen nicht automatisch mit den Interfaces, die sie implementieren.

The generated API documentation for each release is published on twistedmatrix.com, und Sie können es dort durchsuchen.