Docstring
# Docstring

Nella programmazione una docstring è un letterale di tipo stringa inserito nel codice sorgente che ha la funzione, analogamente ad un commento, di documentare una porzione di codice. A differenza dei commenti, in testo semplice o con una formattazione particolare come javadoc o doxygen, che vengono ignorati dal parser del compilatore o dell'interprete, le docstring vengono conservate e sono disponibili a runtime, semplificando l'ispezione del codice e fornendo aiuto o metadati durante l'esecuzione.

Tra i linguaggi che supportano le docstring vi sono Python, Lisp, Elixir e Clojure.

## Esempi

### Elixir

Le docstring sono usate in Elixir per la documentazione, e il linguaggio di markup usato come standard de facto è il markdown:

### Lisp

In Lisp, le docstring sono chiamate stringhe di documentazione (documentation strings). Lo standard del Common Lisp stabilisce che le implementazioni possono liberamente ignorare le docstring. Quando esse vengono conservate, possono essere ispezionate e modificate usando la funzione DOCUMENTATION.

### Python

Le docstring in Python vengono usate per documentare il codice e sono inserite come prima istruzione che segue la definizione di funzioni, metodi, moduli e classi, mentre se inserite altrove vengono ignorate. Le docstring sono racchiuse tra tripli apici doppi, e possono contenere interruzioni di riga. Si può accedere alle docstring tramite l'attributo __doc__ di un oggetto. Le linee guida sull'uso delle docstring sono raccolte nella PEP 257 (Python Enhancement Proposal), di livello Informative. Se la docstring è su una sola riga si raccomanda di avere gli apici di apertura e di chiusura sulla stessa riga, mentre se è su più righe si raccomanda di avere un brief sulla stessa riga degli apici di apertura, seguito dai dettagli dopo un salto di riga, e gli apici di chiusura su una nuova riga.

Si può accedere alle docstring in una sessione interattiva dell'interprete:

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, effetti collaterali, 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. Seguono degli esempi di docstring a documentazione di una funzione con alcuni dei principali formati comunemente usati.

Epydoc supporta un formato mutuato da javadoc:

Epydoc e Sphinx supportano il formato reStructuredText (reST):

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:

NumPy ha un suo formato di docstring mutuato dal formato Google, leggibile da Sphinx.

