Che significato hanno questi formati nella docstring di twisted?

Question

Nel codice sorgente di twisted, molte docstrings contengono formati come questo: L {xxx} o C {xxx} o una riga inizia con un '@', qual è il loro significato?

per esempio, in contorto/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, produttore @type?

A proposito, questi formati fanno parte dei formati standard di docstring python? Se sì, dove dovrei fare riferimento? Grazie :)

Answer 1

Il formato di documentazione utilizzato da Twisted è Epytext, which is documented on epydoc.sourceforge.net.

L{} significa "link" (vale a dire "questo è un identificatore Python, si prega di link ad esso") C{} significa "codice" (vale a dire hello C{foo} bar deve essere formattato come "ciao foo bar"). I{} significa solo "in corsivo". Puoi vedere più campi nella documentazione di epytext.

Il progetto Twisted genera la sua documentazione con pydoctor, utilizzando una chiamata come pydoctor --add-package twisted. C'è un po 'di più in esso, per generare collegamenti ad un paio di altri progetti su cui Twisted fa affidamento, ma puoi usarlo per avere un'idea se vuoi contribuire con docstring a Twisted. È anche possibile generare la documentazione con epydoc stesso, usando epydoc twisted, ma epydoc non conosce l'interfaccia Zope e quindi non collegherà automaticamente le classi alle interfacce che implementano.

The generated API documentation for each release is published on twistedmatrix.com, ed è possibile sfogliarlo lì.