Docstring: differenze tra le versioni

Versione delle 00:09, 1 mar 2018

Versione attuale delle 10:25, 30 ago 2024

(5 versioni intermedie di 4 utenti non mostrate)

Riga 1:

Nella [[programmazione (informatica)|programmazione]] una '''docstring''' è un [[letterale (informatica)|letterale]] di tipo [[stringa (informatica)|stringa]] inserito nel [[codice sorgente]] che ha la funzione, analogamente ad un [[commento (informatica)|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 [[Metadato|metadati]] durante l'esecuzione.

Tra i linguaggi che supportano le docstring vi sono [[Python]], [[Lisp]], [[Elixir (linguaggio di programmazione)|Elixir]] e [[Clojure]].<ref>[http{{Cita web |url=https://clojure.github.com/clojure/clojure.core-api.html#clojure.core/defn |titolo=Definizione di funzione con docstring in Clojure] |accesso=1 maggio 2019 |dataarchivio=29 gennaio 2013 |urlarchivio=https://web.archive.org/web/20130129013007/http://clojure.github.com/clojure/clojure.core-api.html#clojure.core/defn |urlmorto=sì }}</ref>

== Esempi ==

=== Elixir ===

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

<sourcesyntaxhighlight lang="ruby">

defmodule MyModule do

@moduledoc """

Riga 17:

end

end

</syntaxhighlight>

</source>

=== 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.<ref>[http://www.lispworks.com/documentation/HyperSpec/Body/f_docume.htm Funzione DOCUMENTATION]</ref>

<sourcesyntaxhighlight lang="lisp">

(defun foo () "questa è una docstring" nil)

(documentation #'foo 'function) => "questa è una docstring"

</syntaxhighlight>

</source>

=== 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 <code>__doc__</code> 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.<ref>[https://www.python.org/dev/peps/pep-0257/ PEP 257]</ref>

<sourcesyntaxhighlight lang="python">

"""programma.py

Riga 46:

def my_function():

"""Docstring della funzione."""

</syntaxhighlight>

</source>

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

<sourcesyntaxhighlight lang="python">

>>> import mymodule

>>> help(mymodule)

Riga 64:

Docstring della funzione.

>>>

</syntaxhighlight>

</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.

Riga 71:

Epydoc supporta un formato mutuato da [[javadoc]]:<ref>{{cita web|url=http://epydoc.sourceforge.net/epydoc.html|titolo=Epydoc}}</ref>

<sourcesyntaxhighlight lang=python>

""" Brief

Riga 81:

@raise Exception: descrizione dell'eccezione lanciata

"""

</syntaxhighlight>

</source>

Epydoc e Sphinx supportano il formato reStructuredText (reST):<ref>{{cita web|url=httphttps://www.sphinx-doc.org/|titolo=Sphinx}}</ref>

<sourcesyntaxhighlight lang=python>

""" Brief

Riga 94:

:raises Exception: descrizione dell'eccezione lanciata

"""

</syntaxhighlight>

</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>{{citaCita web|url=http://google-styleguide.googlecodegithub.comio/svn/trunkstyleguide/pyguide.html#Comments|sitotitolo=google-styleguide.googlecode.com|titolosito=Google Python Style Guidestyleguide|editorelingua=Googleen-US|urlmortoaccesso=sì|urlarchivio=https://web.archive.org/web/20150920230332/http://google2019-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments|dataarchivio=20 settembre 201510-17}}</ref>:

<sourcesyntaxhighlight lang="python">

""" Brief

Descrizione...

Args:

Parameters:

p1 -: descrizione del primo parametro p1

p2 -: descrizione del secondo parametro p2

Returns:

Riga 110:

Raises:

Exception -: descrizione dell'eccezione lanciata

"""

</syntaxhighlight>

</source>

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

<sourcesyntaxhighlight lang=python>

""" Brief

Riga 139:

descrizione dell'eccezione lanciata

"""

</syntaxhighlight>

</source>

== Note ==

Riga 150:

== Collegamenti esterni ==

*{{cita web|http://epydoc.sourceforge.net/docstrings.html|Python Docstrings}}

*{{cita web |1=http://www.linuxselfhelp.com/gnu/elisp/html_chapter/elisp_24.html#SEC361 |2=Documentazione in GNU Emacs Lisp |accesso=18 aprile 2015 |urlarchivio=https://web.archive.org/web/20160303174051/http://www.linuxselfhelp.com/gnu/elisp/html_chapter/elisp_24.html#SEC361 |dataarchivio=3 marzo 2016 |urlmorto=sì }}

*[httphttps://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks Sezione] sulle docstring nella documentazione di [[doxygen]]

{{portale|informatica}}