Come documentare un metodo con i parametri?

Question

Come documentare metodi con parametri usando le stringhe di documentazione di Python?

EDIT: PEP 257 dà questo esempio:

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    Keyword arguments: 
    real -- the real part (default 0.0) 
    imag -- the imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

E 'questa la convenzione usata dalla maggior parte degli sviluppatori Python?

Keyword arguments: 
<parameter name> -- Definition (default value if any) 

mi aspettavo qualcosa di un po 'più formale, come ad esempio

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    @param: real The real part (default 0.0) 
    @param: imag The imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

Environnement: Python 2.7.1

Answer 1

Sulla base della mia esperienza, il numpy docstring conventions (PEP257 superset) sono i più ampiamente diffusa seguito convenzioni che sono supportati anche da strumenti come Sphinx.

Un esempio:

Parameters 
---------- 
x : type 
    Description of parameter `x`. 

Answer 2

Convenzioni:

• PEP 257 Docstring Conventions
• PEP 287 reStructuredText Docstring Format

Strumenti:

• Epydoc: Automatic API Documentation Generation for Python
• sphinx.ext.autodoc – Include documentation from docstrings
• PyCharm has some nice support for docstrings

---

Aggiornamento: Dal momento che Python 3.5 è possibile utilizzare type hints che è un compatto, leggibile dalla macchina sintassi:

from typing import Dict, Union 

def foo(i: int, d: Dict[str, Union[str, int]]) -> int: 
    """ 
    Explanation: this function takes two arguments: `i` and `d`. 
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys 
    and values that can be either `str` or `int`. 

    The return type is `int`. 

    """ 

Il vantaggio principale di questa sintassi è che è definito dal linguaggio e che è priva di ambiguità, in modo da strumenti come PyCharm possono facilmente trarre vantaggio da esso.

Answer 3

le stringhe in python doc sono in forma libera, è possibile documentarlo in qualsiasi modo.

Esempi:

def mymethod(self, foo, bars): 
    """ 
    Does neat stuff! 
    Parameters: 
     foo - a foo of type FooType to bar with. 
     bars - The list of bars 
    """ 

Ora, ci sono alcune convenzioni, ma Python non rispettare nessuno di loro. Alcuni progetti hanno le proprie convenzioni. Alcuni strumenti per lavorare con docstrings seguono anche convenzioni specifiche.

Answer 4

Le didascalie sono utili solo negli ambienti interattivi, ad es. la shell di Python. Quando si documentano oggetti che non verranno utilizzati in modo interattivo (ad esempio oggetti interni, callback di framework), si potrebbe usare anche commenti regolari. Qui è uno stile che uso per appendere i commenti rientrate sconto elementi, ciascuno sulla propria linea, in modo da sapere che il commento chiede di:

def Recomputate \ 
    (
    TheRotaryGyrator, 
     # the rotary gyrator to operate on 
    Computrons, 
     # the computrons to perform the recomputation with 
    Forthwith, 
     # whether to recomputate forthwith or at one's leisure 
) : 
    # recomputates the specified rotary gyrator with 
    # the desired computrons. 
    ... 
#end Recomputate 

Non si può fare questo genere di cose con docstring.

Answer 5

Se si prevede di utilizzare Sfinge per documentare il codice, è in grado di produrre documenti HTML ben formattata per i parametri con la loro funzione di 'firme'. http://sphinx-doc.org/domains.html#signatures

Answer 6

Il mainstream è, come già indicato in altre risposte, probabilmente con lo Sphinx way in modo che sia possibile utilizzare Sphinx per generare quei documenti di fantasia in seguito.

Detto questo, di tanto in tanto utilizzo lo stile di commento in linea.

def complex( # Form a complex number 
     real=0.0, # the real part (default 0.0) 
     imag=0.0 # the imaginary part (default 0.0) 
     ): # Returns a complex number. 
    """Form a complex number. 

    I may still use the mainstream docstring notation, 
    if I foresee a need to use some other tools 
    to generate an HTML online doc later 
    """ 
    if imag == 0.0 and real == 0.0: 
     return complex_zero 
    other_code() 

Un altro esempio qui, con alcuni dettagli molto piccoli in linea documentato:

def foo( # Note that how I use the parenthesis rather than backslash "\" 
      # to natually break the function definition into multiple lines. 
     a_very_long_parameter_name, 
      # The "inline" text does not really have to be at same line, 
      # when your parameter name is very long. 
      # Besides, you can use this way to have multiple lines doc too. 
      # The one extra level indentation here natually matches the 
      # original Python indentation style. 
      # 
      # This parameter represents blah blah 
      # blah blah 
      # blah blah 
     param_b, # Some description about parameter B. 
      # Some more description about parameter B. 
      # As you probably noticed, the vertical alignment of pound sign 
      # is less a concern IMHO, as long as your docs are intuitively 
      # readable. 
     last_param, # As a side note, you can use an optional comma for 
        # your last parameter, as you can do in multi-line list 
        # or dict declaration. 
     ): # So this ending parenthesis occupying its own line provides a 
      # perfect chance to use inline doc to document the return value, 
      # despite of its unhappy face appearance. :) 
    pass 

I benefici (come @ mark-Horvath già sottolineato in un altro commento) sono:

• Most importantemente, i parametri e il loro documento rimangono sempre uniti, il che porta i seguenti vantaggi:
• Meno digitazioni (non è necessario ripetere il nome della variabile)
• Manutenzione semplificata in caso di modifica/rimozione della variabile. Non ci sarà mai alcun paragrafo del parametro dei parametri orfani dopo aver rinominato qualche parametro.
• e più facile da trovare il commento mancante.

Ora, alcuni potrebbero pensare che questo stile sia "brutto". Ma direi che "brutto" è una parola soggettiva. Un modo più neutrale è quello di dire che questo stile non è mainstream quindi potrebbe sembrare meno familiare, quindi meno confortevole. Ancora una volta, "comodo" è anche una parola soggettiva. Ma il punto è che tutti i benefici sopra descritti sono oggettivi. Non è possibile raggiungerli nel modo standard.

Speriamo che un giorno, in futuro, ci sarà uno strumento generatore di documenti che può anche consumare tale stile in linea. Ciò guiderà l'adozione.

PS: questa risposta deriva dalla mia preferenza di utilizzare i commenti in linea ogni volta che ritengo opportuno. Io uso anche lo same inline style to document a dictionary.

Answer 7

Poiché le docstring sono in formato libero, in realtà dipende da ciò che viene utilizzato per analizzare il codice per generare la documentazione dell'API.

Si consiglia di familiarizzare con lo Sphinx markup, poiché è ampiamente utilizzato e sta diventando lo standard di fatto per la documentazione di progetti Python, in parte a causa dell'ottimo servizio readthedocs.org. Per paraphrase an example dalla documentazione Sfinge come un frammento di codice Python:

def send_message(sender, recipient, message_body, priority=1): 
    ''' 
    Send a message to a recipient 

    :param str sender: The person sending the message 
    :param str recipient: The recipient of the message 
    :param str message_body: The body of the message 
    :param priority: The priority of the message, can be a number 1-5 
    :type priority: integer or None 
    :return: the message id 
    :rtype: int 
    :raises ValueError: if the message_body exceeds 160 characters 
    :raises TypeError: if the message_body is not a basestring 
    ''' 

Questo markup supporta cross-referencing tra i documenti e altro ancora. Si noti che la documentazione di Sphinx utilizza (ad es.) :py:attr: mentre si può semplicemente usare :attr: quando si documenta dal codice sorgente.

Naturalmente, esistono altri strumenti per documentare le API. C'è il più classico Doxygen che usa \paramcommands ma quelli non sono specificamente progettati per documentare il codice Python come Sphinx.

Nota che c'è un similar question con un similar answer qui ...