Doxygen/it

Introduzione
Doxygen è uno strumento popolare per la generazione di documentazione da sorgenti C++ annotate; supporta anche altri linguaggi di programmazione popolari come C#, PHP, Java e Python. Visitare il sito web Doxygen per saperne di più sul sistema e consultare il Manuale Doxygen per informazioni complete.



Doxygen e FreeCAD
Questo documento fornisce una breve introduzione a Doxygen, in particolare a come viene utilizzato in FreeCAD per documentarne i sorgenti. Visitare la pagina documentazione del codice sorgente per istruzioni sulla creazione della documentazione di FreeCAD, anch'essa ospitata online sul sito web dell'API di FreeCAD.





Doxygen col codice C++
La sezione Getting started (Step 3) del manuale Doxygen menziona i modi di base per documentare le fonti.

Per i membri, le classi e gli spazi dei nomi ci sono fondamentalmente due opzioni:
 * 1) Posizionare uno speciale "blocco di documentazione" (un paragrafo commentato) prima della dichiarazione o della definizione della funzione, membro, classe o spazio dei nomi. Per i membri di file, delle classi e dello spazio dei nomi (variabili) è anche consentito posizionare la documentazione direttamente dopo il membro. Vedere la sezione Blocchi di commenti speciali nel manuale per saperne di più su questi blocchi.
 * 2) Posizionare un blocco di documentazione speciale da qualche altra parte (un altro file o un'altra posizione nello stesso file) e inserire un "comando strutturale" nel blocco di documentazione. Un comando strutturale collega un blocco di documentazione a una determinata entità che può essere documentata (una funzione, un membro, una variabile, una classe, uno spazio dei nomi o un file). Vedere la sezione Documentazione in altri luoghi ​​nel manuale per saperne di più sui comandi strutturali.

Nota:
 * Il vantaggio della prima opzione è che non si deve ripetere il nome dell'entità (funzione, membro, variabile, classe o spazio dei nomi), poiché Doxygen analizzerà il codice ed estrarrà le informazioni rilevanti.
 * I file possono essere documentati solo utilizzando la seconda opzione, poiché non è possibile inserire un blocco di documentazione prima di un file. Naturalmente, i membri del file (funzioni, variabili, typedef, define) non necessitano di un comando strutturale esplicito; semplicemente mettendo un blocco di documentazione prima o dopo di questi tutto funzionerà correttamente.



Primo stile: blocco della documentazione prima del codice
Di solito si desidera documentare il codice nel file di intestazione, appena prima della dichiarazione di classe o del prototipo di funzione. Ciò mantiene la dichiarazione e la documentazione vicine l'una all'altra, quindi è facile aggiornare quest'ultima se la prima cambia.

Il blocco di documentazione speciale inizia come un commento in stile C ma ha un asterisco aggiuntivo, quindi ; il blocco termina con un  corrispondente. Un'alternativa è utilizzare i commenti in stile C++ con una barra aggiuntiva, quindi.



Secondo stile: blocco della documentazione altrove
In alternativa, la documentazione può essere collocata in un altro file (o nello stesso file in alto o in basso, o dovunque), lontano dalla dichiarazione di classe o dal prototipo di funzione. In questo caso, avrai informazioni duplicate, una volta nel file di origine effettivo e una volta nel file di documentazione.

Primo file, :

Secondo file, :

In questo caso viene usato il comando strutturale per indicare quale file sorgente si sta documentando; un comando strutturale  indica che il seguente codice è una funzione, e il comando  è usato per dare una breve descrizione di questa funzione.

Questo modalità di documentare un file sorgente è utile se vuoi solo aggiungere documentazione al tuo progetto senza aggiungere codice reale. Quando si inserisce un blocco di commento in un file con una delle seguenti estensioni, o , Doxygen analizzerà i commenti e creerà la documentazione appropriata, ma nasconderà questo file ausiliario dall'elenco dei file.

Il progetto FreeCAD contiene diversi file che terminano con in molte cartelle per fornire una descrizione, o esempi, del codice presente. È importante che tali file siano correttamente categorizzati in un gruppo o in uno spazio dei nomi, per il quale Doxygen fornisce alcuni comandi ausiliari come, e.

Esempio ; questo file nell'albero dei sorgenti di FreeCAD fornisce una breve spiegazione dello spazio dei nomi.

Un altro esempio è il file. Prima dei dettagli di implementazione dei metodi, c'è un blocco di documentazione che spiega alcuni dettagli del framework di comando di FreeCAD. Ha vari comandi per strutturare la documentazione. Include anche codice di esempio racchiuso in una coppia di parole chiave e ; quando il file viene elaborato da Doxygen, questo esempio di codice verrà appositamente formattato per distinguersi. La parola chiave viene utilizzata in diversi punti per creare collegamenti a sezioni, sottosezioni, pagine o ancore denominate altrove nella documentazione. Allo stesso modo, i comandi o  stampano "Vedi anche" e forniscono un collegamento ad altre classi, funzioni, metodi, variabili, file o URL. Esempio



Esempio dal progetto VTK
Questo è un esempio da, una libreria di visualizzazione 3D utilizzata per presentare dati scientifici, come risultati di elementi finiti e informazioni sulla nuvola di punti.

Una classe per archiviare una raccolta di coordinate è definita in un file di intestazione C++. La parte superiore del file è commentata e vengono utilizzate alcune parole chiave, come, e  per indicare parti importanti. All'interno della classe, prima dei prototipi del metodo della classe, un blocco di testo commentato spiega cosa fa la funzione ei suoi argomenti.
 * Codice sorgente di vtkArrayCoordinates.h.
 * Doxygen ha prodotto la documentazione per la classe vtkArrayCoordinates.



Compilazione della documentazione


Per generare la documentazione del codice sorgente ci sono due passaggi fondamentali:
 * 1) Creare un file di configurazione per controllare come Doxygen elaborerà i file sorgente.
 * 2) Eseguire  su quella configurazione.

Il processo è descritto di seguito.


 * Assicurarsi di avere i programmi e  nel proprio sistema. Si consiglia inoltre di avere il programma  da, per generare diagrammi con le relazioni tra classi e spazi dei nomi. Sui sistemi Linux questi programmi possono essere installati dal tuo gestore di pacchetti.


 * Assicurarsi di essere nella stessa cartella dei tuoi file di origine, o nella directory di livello superiore del tuo albero di origine, se si hanno molti file di origine in diverse sotto cartelle.


 * Eseguire per creare un file di configurazione chiamato . Se si omette questo nome, il valore predefinito sarà  senza estensione.
 * Questo è un grande file di testo semplice che include molte variabili con i loro valori. Nel manuale Doxygen queste variabili sono chiamate "tag". Il file di configurazione e tutti i tag sono ampiamente descritti nella sezione Configurazione del manuale. È possibile aprire il file con qualsiasi editor di testo e modificare il valore di ogni tag secondo necessità. Nello stesso file puoi leggere i commenti che spiegano ciascuno dei tag e i loro valori predefiniti.


 * Invece di utilizzare un editor di testo, si può avviare per modificare più tag contemporaneamente. Con questa interfaccia è possibile definire molte proprietà come informazioni sul progetto, tipo di output (HTML e LaTeX), utilizzo di Graphviz per creare diagrammi, messaggi di avviso da visualizzare, modelli di file (estensioni) da documentare o escludere, filtri di input, intestazioni opzionali e piè di pagina per le pagine generate in HTML, opzioni per output LaTeX, RTF, XML o Docbook e molte altre opzioni.


 * Un'altra opzione è creare il file di configurazione da zero e aggiungere solo i tag desiderati con un editor di testo.
 * Dopo aver salvato la configurazione, si può eseguire Doxygen su questo file di configurazione.


 * La documentazione generata verrà creata all'interno di una cartella denominata . Consisterà in molte pagine HTML, immagini PNG per la grafica, fogli di stile a cascata, file Javascript e potenzialmente molte sotto cartelle con più file a seconda sulla dimensione del codice. Il punto di accesso alla documentazione è , che si può aprire con un browser web.

Se si stanno scrivendo nuove classi, funzioni o un intero nuovo workbench, si consiglia di eseguire periodicamente per verificare che la documentazione blocchi Markdown e special commands vengano letti correttamente e che tutte le funzioni pubbliche siano completamente documentate. Si prega di leggere anche i suggerimenti per la documentazione che si trovano nel codice sorgente.

Quando si genera la documentazione completa di FreeCAD, non si esegue direttamente. Invece, il progetto utilizza per configurare l'ambiente di compilazione, quindi  avvia la compilazione dei sorgenti di FreeCAD e della documentazione di Doxygen; questo è spiegato nella pagina documentazione sorgente.



markup di Doxygen
Tutti i comandi di documentazione di Doxygen iniziano con una barra rovesciata  o un simbolo at, a scelta. Normalmente si usa la barra rovesciata, ma occasionalmente si usa per migliorare la leggibilità.

I comandi possono avere uno o più argomenti. Nel manuale Doxygen gli argomenti sono descritti come segue.
 * Se vengono utilizzate parentesi con segno minore e maggiore l'argomento è una singola parola.
 * Se vengono utilizzate parentesi tonde l'argomento si estende fino alla fine della riga in cui è stato trovato il comando.
 * Se vengono utilizzate le parentesi graffe  l'argomento si estende fino al paragrafo successivo. I paragrafi sono delimitati da una riga vuota o da un indicatore di sezione.
 * Se si usano le parentesi quadre l'argomento è facoltativo.

Alcune delle parole chiave più comuni utilizzate nella documentazione di FreeCAD sono presentate qui.
 * , vedere \defgroup, e Grouping.
 * , vedere \ingroup, e Grouping.
 * , vedere \addtogroup, e Grouping.
 * , vedere \author; indica l'autore di questo pezzo di codice.
 * , vedere \brief; descrive brevemente la funzione.
 * , vedere \file; documenta un file di origine o di intestazione.
 * , see \page; inserisce le informazioni in una pagina separata, non direttamente correlata a una specifica classe, file o membro.
 * , vedere \package; indica la documentazione per un pacchetto Java (ma è utilizzato anche con Python).
 * , vedere \fn; documenta una funzione.
 * , vedere \var; documenta una variabile; è equivalente a, , e.
 * , vedere \section; inizia una sessione.
 * , vedere \subsection; inizia una sottosessione.
 * , vedere \namespace; indica le informazioni per uno spazio dei nomi.
 * , e, vedere \cond; definisce un blocco da documentare o omettere in modo condizionale.
 * , vedere \a; visualizza l'argomento in corsivo per dare enfasi.
 * , vedere \param; indica il parametro di una funzione.
 * , vedere \return; specifica il valore restituito.
 * , vedere \sa; stampa "See also".
 * , vedere \note; aggiunge un paragrafo da utilizzare come nota.



Supporto al Markdown
A partire da Doxygen 1.8, la sintassi Markdown è riconosciuta dai blocchi di documentazione. Markdown è un linguaggio di formattazione minimalista ispirato all'e-mail di testo semplice che, simile alla sintassi wiki, intende essere semplice e leggibile senza richiedere codice complicato come quello che si trova in HTML, LaTeX o i comandi di Doxygen. Markdown ha guadagnato popolarità con il software libero, specialmente nelle piattaforme online come Github, in quanto consente di creare documentazione senza utilizzare codice complicato. Consultare la sezione Markdown support nel manuale Doxygen per saperne di più. Visitare il sito web di Markdown per saperne di più sull'origine e la filosofia di Markdown.

Doxygen supporta un set standard di istruzioni Markdown, nonché alcune estensioni come Github Markdown. Di seguito vengono presentati alcuni esempi di formattazione Markdown.

Quello che segue è Markdown standard. {{Code|code= Ecco il testo per un paragrafo.

Continuiamo con altro testo in un altro paragrafo.

Questa è un'intestazione di livello 1

=
===========

Questa è un'intestazione di livello 2


 * 1) Questa è un'intestazione di livello 1


 * 1) Questa è l'intestazione di livello 3 #######

> Questa è un blocco di citazione > su più righe

- Articolo 1

Altro testo per questo articolo.

- Punto 2 * voce di elenco nidificata. * un altro elemento nidificato. - Punto 3

1. Primo elemento. 2. Secondo elemento.


 * asterisco singolo: enfasi*

_sottolineature singole_

**doppio asterisco: enfasi forte**

__sottolineature doppie__

Questo è un paragrafo normale

Questo è un blocco di codice

Continuiamo di nuovo con un paragrafo normale.

Usa la funzione `printf`. `codice` inline.

[Il testo del link](http://example.net/)

![Testo della didascalia](/path/to/img.jpg)

 }}

Le seguenti sono estensioni di Markdown. [TOC]

Prima intestazione   | Seconda intestazione --| - Contenuto della Cella | Contenuto della Cella Contenuto della Cella | Contenuto della Cella

~ {.py} class Dummy: pass ~
 * 1) A class

~ {.c} int func(int a, int b) { return a*b; } ~

``` int func(int a, int b) { return a*b; } ```



Analisi dei blocchi della documentazione
Il testo all'interno di uno speciale blocco di documentazione viene analizzato prima di essere scritto nei file di output HTML e LaTeX. Durante l'analisi si verificano i seguenti passaggi:
 * La formattazione Markdown è sostituita dall'HTML corrispondente o da comandi speciali.
 * Vengono eseguiti i comandi speciali all'interno della documentazione. Vedere la sezione Comandi speciali nel manuale per una spiegazione di ciascun comando.
 * Se una riga inizia con degli spazi bianchi seguiti da uno o più asterischi e poi facoltativamente altri spazi bianchi, tutti gli spazi bianchi e gli asterischi vengono rimossi.
 * Tutte le righe vuote risultanti vengono trattate come separatori di paragrafo.
 * I collegamenti vengono creati automaticamente per le parole corrispondenti a classi o funzioni documentate. Se la parola è preceduta da un simbolo di percentuale, questo simbolo viene rimosso e non viene creato alcun collegamento per la parola.
 * I collegamenti vengono creati quando nel testo vengono trovati determinati schemi. Vedere la sezione Generazione automatica di link nel manuale per ulteriori informazioni.
 * I tag HTML presenti nella documentazione vengono interpretati e convertiti in equivalenti LaTeX per l'output LaTeX. Vedere la sezione Comandi HTML nel manuale per una spiegazione di ciascun tag HTML supportato.



Doxygen con codice Python
Doxygen funziona meglio per linguaggi tipizzati staticamente come C++. Tuttavia, può anche creare documentazione per i file Python.

Esistono due modi per scrivere blocchi di documentazione per Python:
 * 1) Il modo Pythonico, usando "docstrings", cioè un blocco di testo racchiuso tra   subito dopo la definizione della classe o della funzione.
 * 2) Il modo Doxygen, inserendo i commenti prima della definizione della classe o della funzione; in questo caso vengono utilizzati i doppi caratteri hash  per iniziare il blocco di documentazione, e quindi un singolo carattere hash può essere utilizzato nelle righe successive.

Nota:
 * La prima opzione è preferita per rispettare PEP8, pep-0257/ PEP257 e la maggior parte delle linee guida di stile per la scrittura di Python (vedere 1, 2). Si consiglia di utilizzare questo stile se si intende produrre fonti documentate utilizzando Sphinx, che è uno strumento molto comune per documentare il codice Python. Se usi questo stile, Doxygen sarà in grado di estrarre i commenti alla lettera, ma i comandi speciali di Doxygen che iniziano con o  non funzioneranno.
 * La seconda opzione non è il tradizionale stile Python, ma ti permette di usare i comandi speciali di Doxygen come e.



Primo stile: documentazione Pythonica
Nell'esempio seguente una docstring è all'inizio per spiegare i contenuti generali di questo modulo (file). Quindi le docstring appaiono all'interno delle definizioni di funzione, classe e metodo di classe. In questo modo Doxygen estrarrà i commenti e li presenterà così come sono, senza modifiche.



Secondo stile: blocco di documentazione prima del codice
Nell'esempio seguente i blocchi di documentazione iniziano con doppi cancelletti. Uno appare all'inizio per spiegare il contenuto generale di questo modulo (file). Quindi ci sono blocchi prima delle definizioni di funzione, classe e metodo di classe e c'è un blocco dopo una variabile di classe. In questo modo, Doxygen estrarrà la documentazione, riconoscerà i comandi speciali, e  e formatterà il testo di conseguenza.



Compilazione della documentazione
La compilazione della documentazione procede come per i sorgenti C++. Se entrambi i file Python, e, con uno stile di commento distinto si trovano nella stessa directory, verranno elaborati entrambi.

La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli e classi.



Conversione dello stile Pythonico in stile Doxygen
Nell'esempio precedente, il file Python commentato in un stile Doxygen mostra informazioni e formattazione più dettagliate per le sue classi, funzioni e variabili. Il motivo è che questo stile consente a Doxygen di estrarre i comandi speciali che iniziano con o, mentre lo stle Pythonico no. Pertanto, sarebbe desiderabile convertire lo stile Pythonico in stile Doxygen prima di compilare la documentazione. Questo è possibile con un programma Python ausiliario chiamato doxypypy. Questo programma è ispirato a un vecchio programma chiamato doxypy, che prende le  e le converte nei blocchi di commenti Doxygen che iniziano con un doppio hash. Doxypypy va oltre, poiché analizza le docstring ed estrae elementi di interesse come variabili e argomenti e persino doctest (codice di esempio nelle docstring).

Doxypypy può essere installato usando, il programma di installazione dei pacchetti Python.

Se il comando viene utilizzato senza l'opzione, saranno necessari i privilegi di superutente (root) per installare il pacchetto, ma ciò non è necessario nella maggior parte dei casi; usare i permessi di root solo se sei certo che il pacchetto non entrerà in collisione con i pacchetti forniti dalla tua distribuzione.

Se il pacchetto è stato installato come utente, potrebbe risiedere nella tua home directory, ad esempio in. Se questa directory non è nel del tuo sistema, il programma non verrà trovato. Pertanto, aggiungere la directory alla variabile, nel file o nel file.

In alternativa, si può creare un collegamento simbolico al programma, posizionando il collegamento in una directory che è già inclusa nel.

Una volta che il programma è installato e accessibile dal terminale, un file Python con docstring Pythonic può essere riformattato in stile Doxygen con le seguenti istruzioni. Il programma invia il codice riformattato allo standard output, quindi reindirizza questo output a un nuovo file.

Il file originale ha un commento in alto  che indica il modulo o lo spazio dei nomi che viene descritto dal file. Questa parola chiave non viene interpretata quando si utilizzano le virgolette triple nel blocco dei commenti.

Nel nuovo file lo stile di commento è cambiato in modo che la riga diventi, che ora sarà interpretata da Doxygen. Tuttavia, per essere interpretato correttamente, l'argomento deve essere modificato manualmente in modo che corrisponda al nome del nuovo modulo (file); dopo aver fatto questo la riga dovrebbe essere.

div class="mw-collapsible mw-collapsed toccolours"> (la parte superiore viene modificata manualmente, il resto rimane invariato)

Per compilare, creare la configurazione ed eseguire nella directory di livello superiore che contiene i file.

La documentazione dovrebbe mostrare informazioni simili alle seguenti e creare collegamenti appropriati ai singoli moduli.



Conversione immediata dello stile del commento
Nell'esempio precedente, la conversione dei blocchi di documentazione è stata eseguita manualmente con un solo file sorgente. Idealmente si desidera che questa conversione avvenga automaticamente, al volo, con qualsiasi numero di file Python. Per fare ciò, la configurazione Doxygen deve essere modificata di conseguenza.

Per iniziare, non utilizzare direttamente il programma ; invece, creare il file di configurazione con, quindi modificare il creato e modificare il seguente tag.

Quello che fa è che i file che corrispondono al modello, tutti i file con un'estensione che termina con, passeranno attraverso il programma. Ogni volta che Doxygen incontra tale file nell'albero dei sorgenti, il nome del file verrà passato come primo argomento a questo programma.

Il programma non esiste di default; dovrebbe essere creato come uno script di shell per eseguire  con le opzioni appropriate e per prendere un file come primo argomento.

Dopo aver salvato questo script di shell, assicurarsi che abbia i permessi di esecuzione e che si trovi in una directory contenuta nel del tuo sistema.

Sui sistemi Windows, un file batch può essere utilizzato in modo simile.

Con questa configurazione impostata, il comando può essere eseguito per generare la documentazione come di consueto. Per ogni file Python che usa  Pythonic sarà riformattato al volo per usare i commenti in stile, e poi questi saranno elaborati da Doxygen, che quindi sarà in grado di interpretare i comandi speciali e la sintassi markdown. Il codice sorgente originale non verrà modificato e non è necessario creare alcun file temporaneo con un nome diverso come nella sezione precedente; pertanto, se viene trovata un'istruzione, non è necessario modificarla manualmente.

Nota che i file Python esistenti che usano già lo stile per i loro blocchi di commenti non saranno influenzati dal filtro  e saranno processati normalmente da Doxygen.



<span id="Python_code_quality_check">

Controllo della qualità del codice Python
Per utilizzare la conversione automatica dei blocchi di documentazione è importante che i sorgenti Python originali siano scritti correttamente, seguendo le linee guida Pythonic in PEP8 e. Un codice scritto in modo approssimativo causerà il fallimento di durante l'elaborazione del file, e quindi Doxygen non sarà in grado di formattare correttamente la documentazione.

I seguenti stili di commento non consentiranno l'analisi delle docstring da parte di, quindi dovrebbero essere evitati.

Usa sempre le virgolette triple per le docstring e assicurati che seguano immediatamente la dichiarazione della classe o della funzione.

È anche una buona idea verificare la qualità del tuo codice Python con uno strumento come flake8 (Gitlab). Flake8 combina principalmente tre strumenti, Pyflakes, Pycodestyle (precedentemente pep8) e /PyCQA/mccabe Controllo della complessità di McCabe, al fine di applicare il corretto stile Pythonic.

Per controllare tutti i file all'interno di un albero dei sorgenti usa.

Se il progetto lo richiede, alcuni controlli del codice ritenuti troppo severi possono essere ignorati. I codici di errore possono essere consultati nella Documentazione di Pycodestyle.

In modo simile, un programma che controlla principalmente che i commenti siano conformi a PEP257 è Pydocstyle. I codici di errore possono essere consultati nella documentazione di Pydocstyle.

Usalo anche con per eseguire controlli docstring su tutti i file sorgente.

<span id="Source_documentation_with_Sphinx">

Documentazione del sorgente con Sphinx
Sphinx è il sistema più popolare per documentare il codice sorgente Python. Tuttavia, poiché le funzioni principali e gli ambienti di lavoro di FreeCAD sono scritti in C++, si è ritenuto che Doxygen fosse uno strumento di documentazione migliore per questo progetto.

Mentre Sphinx può analizzare in modo nativo le docstring Python, analizzare i sorgenti C++ richiede un po' più di lavoro. Il progetto Breathe (Github) è un tentativo di colmare il divario tra Sphinx e Doxygen, al fine di integrare la documentazione del codice sorgente sia Python che C++ nello stesso sistema. Innanzitutto, Doxygen deve essere configurato per produrre un file XML; l'output XML viene quindi letto da Breathe e convertito in input adatto per Sphinx.

Consultare la Guida rapida della documentazione di Breathe per saperne di più su questo processo.

Vedi questa risposta in Stackoverflow per altre alternative alla documentazione del codice C++ e Python insieme nello stesso progetto.

Relazioni

 * Documentazione del sorgente
 * Sito web della API di FreeCAD