Docstring: differenze tra le versioni
Contenuto cancellato Contenuto aggiunto
←Nuova pagina: Nella programmazione (informatica) una '''docstring''' è un letterale (informatica) di tipo stringa (informatica) inserito nel codice sorgente che h... |
→Python: principali formati di docstring Python |
||
Riga 50:
Si può accedere alle docstring in una sessione interattiva dell'interprete:
<source lang="
>>> import mymodule
>>> help(mymodule)
Riga 67:
</source>
La docstring di uno script deve essere usabile come messaggio all'utente, documentandone uso, parametri e sintassi in modo dettagliato. La docstring di un modulo elenca usualmente classi, eccezioni e funzioni esportate dal modulo, con una riga di spiegazione per ognuno dei componenti. Quella di un package usualmente riporta anche moduli e subpackage esportati dal package. La docstring di un metodo è tipicamente una frase di un solo periodo che riporta in maniera coincisa l'effetto ("Fa ''x''", "Restituisce ''y''"), senza dilungarsi in descrizioni, oppure può essere una docstring multilinea che dopo una riga di descrizione sommaria riporta i dettagli di tutti i parametri (anche opzionali), valori restituiti, [[effetto collaterale (informatica)|effetti collaterali]], [[eccezione (informatica)|eccezioni]] e restrizioni d'uso. La docstring di una classe riassume il comportamento della stessa e usualmente elenca i metodi e gli attributi, eventuali interfacce per sottoclassi. Il costruttore e i metodi dovrebbero essere documentati in dettaglio nelle relative docstring.
==== Formati ====
La già citata PEP 257 non specifica un formato particolare per la documentazione. Vari formati sono di uso comune, a seconda delle convenzioni o dagli strumenti di generazione automatica della documentazione adottati nei progetti da documentare. Di seguito degli esempi di docstring a documentazione di una funzione, con alcuni i principali formati comunemente usati.
Epydoc supporta un formato mutuato da [[javadoc]]:<ref>{{cita web|url=http://epydoc.sourceforge.net/epydoc.html|titolo=Epydoc}}</ref>
<source lang=python>
""" Brief
Descrizione...
@param p1: descrizione del primo parametro p1
@param p2: descrizione del secondo parametro p2
@return: descrizione del valore di ritorno della funzione
@raise Exception: descrizione dell'eccezione lanciata
"""
</source>
Epydoc e Sphinx supportano il formato reStructuredText (reST):<ref>{{cita web|url=http://sphinx-doc.org/|titolo=Sphinx}}</ref>
<source lang=python>
""" Brief
Descrizione...
:param p1: descrizione del primo parametro p1
:param p2: descrizione del secondo parametro p2
:returns: descrizione del valore di ritorno della funzione
:raises Exception: descrizione dell'eccezione lanciata
"""
</source>
Le convenzioni stilistiche di Google specificano un loro formato, usato nei progetti in Python di Google e piuttosto diffuso anche altrove, che è anche leggibile da Sphinx:<ref>{{cita web|url=http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments|sito=google-styleguide.googlecode.com|titolo=Google Python Style Guide|editore=Google}}</ref>
<source lang=python>
""" Brief
Descrizione...
Parameters:
p1 - descrizione del primo parametro p1
p2 - descrizione del secondo parametro p2
Returns:
Descrizione del valore di ritorno
Raises:
Exception - descrizione dell'eccezione lanciata
"""
</source>
[[NumPy]] ha un suo formato di docstring mutuato dal formato Google, leggibile da Sphinx.
<source lang=python>
""" Brief
Descrizione...
Parameters
----------
p1 : tipo
descrizione del primo parametro p1
p2 : tipo
descrizione del secondo parametro p2
p3 : tipo, optional
descrizione del terzo parametro opzionale p3
Returns
-------
tipo
descrizione del tipo di ritorno
Raises
------
Exception
descrizione dell'eccezione lanciata
"""
</source>
== Voci correlate ==
| |||