Utilizzo di javadoc per la documentazione di Python [chiuso]


162

Attualmente sto iniziando con Python e ho un forte background in PHP e in PHP ho preso l'abitudine di usarlo javadoccome modello di documentazione.

Mi chiedevo se javadocha il suo posto come docstringdocumentazione in Python. Quali sono le convenzioni stabilite e / o le corporazioni ufficiali qui?

Ad esempio, qualcosa del genere è troppo elaborato per adattarsi alla mentalità di Python o dovrei cercare di essere il più conciso possibile?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

E se sono un po 'troppo esaustivo, dovrei scegliere qualcosa del genere (dove la maggior parte della documentazione non viene stampata con il __doc__metodo)?

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

6
Ci sono anche molte altre risposte a questo alla prima domanda di cui si tratta di un duplicato.
Alex Dupuy,

Risposte:


227

Dai un'occhiata al formato reStructuredText (noto anche come "reST"), che è un formato di markup in testo normale / docstring e probabilmente il più popolare nel mondo Python. E dovresti certamente guardare a Sphinx , uno strumento per generare documentazione da reStructuredText (usato per esempio la stessa documentazione di Python). Sphinx include la possibilità di estrarre documentazione dai documenti nel proprio codice (vedere sphinx.ext.autodoc ) e riconosce gli elenchi dei campi reST a seguito di determinate convenzioni. Questo è probabilmente diventato (o sta diventando) il modo più popolare per farlo.

Il tuo esempio potrebbe apparire come segue:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

O esteso con le informazioni sul tipo:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

7
cosa fai se devi interrompere una riga per una descrizione lunga? Come sarebbe?
Skylar Saveland,

6
Vedi reStructuredText reference ed elenchi di campi in particolare: docutils.sourceforge.net/docs/ref/rst/…
Steven

6
Si noti che il modo in cui le frasi qui non sono conformi al PEP 257 . Dovrebbe essere Replace template place holder with values.invece di replaces template place holder with values- Notare la frase, la lettera maiuscola all'inizio e il punto (.) Alla fine.
Kratenko,

1
Dalla versione 1.3, Sphinx supporta anche un formato un po 'più bello tramite l' sphinx.ext.napoleonestensione.
Petri,

3
Qualcuno potrebbe indicarmi la migliore documentazione che specifica queste dotstring speciali come ": param ____:" e ": Returns:"? Un documento del genere sembra piuttosto difficile da trovare al momento.
Krumpelstiltskin,

75

Segui la Guida allo stile di Google Python . Nota che Sphinx può anche analizzare questo formato usando l' estensione Napolean , che verrà fornita in pacchetto con Sphinx 1.3 (questo è anche compatibile con PEP257 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Esempio tratto dalla documentazione napoletana collegata sopra.

Un esempio completo su tutti i tipi di dotstring qui .


20
per tutti gli umani là fuori che leggono dotstrings
Waylon Flinn,

1
Aggiornato il link della Guida allo stile di Google Python
confused00

@ confused00 come posso documentare che il mio metodo sta restituendo una matrice di oggetti?
Cito,


25

Lo standard per le stringhe di documentazione di Python è descritto nella proposta 257 di Python Enhancement .

Il commento appropriato per il tuo metodo sarebbe qualcosa di simile

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """

17
PEP257 non dice nulla sulla formattazione effettiva della parte argomento. Dichiara semplicemente che dovrebbe essere scritto e fornisce un esempio. Ma questo è solo un esempio. Pertanto, consiglierei definitivamente di usare la convenzione Sphinx, poiché non rompi PEP257 e usi una formattazione che potrebbe essere analizzata dalla sfinge.
vaab,

7
Tranne che la prima documentazione presentata sopra è brutta e contiene molte informazioni ridondanti per l'uomo. Preferirei usare una convenzione che renda piacevole la lettura del mio codice sorgente senza prima essere analizzato
confused00

1

Dai un'occhiata a Documenting Python , una pagina "rivolta ad autori e potenziali autori di documentazione per Python".

In breve, reStructuredText è ciò che viene utilizzato per documentare Python stesso. La guida per lo sviluppatore contiene un primer reST, una guida di stile e consigli generali per scrivere una buona documentazione.

Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.