Potete documentare una funzione Python dandole una doc string (stringa di documentazione ndr.).
Esempio 2.4. Definire la doc string della funzione buildConnectionString
def buildConnectionString(params): """Build a connection string from a dictionary of parameters. Returns string."""
Le triple virgolette indicano un stringa multilinea. Ogni cosa tra le virgolette iniziali e finali fanno parte di una singola stringa, inclusi il carriage returns ed altri caratteri speciali. Le potete usare ovunque, ma le vedrete quasi sempre usate durante la definizione di una doc string.
 |
|
| Le triple virgolette sono anche un semplice modo per definire una stringa con singole e doppie virgolette, come il qq/.../ del Perl. | |
Ogni cosa in mezzo alle triple virgolette rappresenta la doc string, della funzione, essa documenta ciò che la funzione è in grado di fare. Una doc string, se esiste, deve essere la prima cosa definita in una funzione (i.e. la prima cosa dopo i due punti). Non è necessario dotare la vostra funzione di una doc string, ma è buona cosa farlo sempre. So che avrete sentito questa frase in ogni lezione di programmazione che avete sentito, ma Python vi dà un incentivo: la doc string rimane disponibile durante l'esecuzione del programma come attributo della funzione.
|
|
| Molti IDE di Python usano la doc string per rendere disponibile una documentazione context-sensitive, così quando scrivete il nome di una funzione, la sua doc string appare come tooltip. Questo può essere incredibilmente utile, ma la sua qualità si basa unicamente sulla doc string che avete scritto. | |
Ulteriori letture
- PEP 257 definisce le convenzioni sulle doc string.
- Python Style Guide discute di come scrivere una buona doc string.
- Python Tutorial discute delle convenzioni per spaziare le doc string.