Eclox Doxygen Plugin for Eclipse

Eclox (http://home.gna.org/eclox) è un plugin Eclipse[1] che implementa una semplice interfaccia per il sistema Doxygen. L’obiettivo di Eclox è di fornire un livello d’integrazione leggero del processo di documentazione del software all’interno di Eclipse grazie ad un’interfaccia utente che maschera la “complessità” di Doxygen. In Figura 1 è mostrato uno schema funzionale di Eclox.

Figura 1 Schema funzionale del plugin Eclox.

I punti di maggiore forza sono la facilità di creazione e gestione dei doxyfile grazie all’interfaccia utente, invocazione integrata di Doxygen e infine l’output della lavorazione di Doxygen direttamente sulla console standard di Eclipse.

Purtroppo da dicembre 2009 lo sviluppo e manutenzione di Eclox è stato interrotto. La versione in questo momento disponibile è la 0.8.0, dichiarata compatibile con la versione 3.3.x e successive di Eclipse. Personalmente ho installato l’ultima versione di Eclox su Eclipse PDT 2.2 senza nessun problema.

L’attuale versione di Eclox se non ricordo male è basata sulla versione 1.5 di Doxygen, questo non compromette comunque il funzionamento del plugin anche su di una versione superiore di Doxygen (come nel mio caso che ho installato sulla mia macchina la versione 1.7 di Doxygen) a meno che non si abbia l’intenzione di utilizzare caratteristiche particolari di Doxygen introdotte con le versioni successive alla 1.5.

Andando direttamente alla parte pratica, generare la documentazione tramite l’ausilio di questo strumento è molto semplice, gli step sono:

• Assicurarsi di aver installato e configurato correttamente Doxygen;
• Installare il plugin Eclox su Eclipse seguendo la procedura standard o seguire le indicazioni che riportate sulla pagina http://home.gna.org/eclox/#download;
• Configurare il plugin. Operazione necessaria quando il plugin non riesce a trovare sul sistema l’installazione di Doxygen, magari perché non è stato installato all’interno di una locazione standard come potrebbe essere /usr o /usr/local oppure il path d’installazione di Doxygen non è definito nella variabile d’ambiente PATH;
• Creare il doxyfile all’interno del progetto di cui si vuole generare la documentazione;
• Eseguire il processo di creazione della documentazione.

In questi casi le illustrazioni valgono più di mille parole scritte, a seguire è quindi mostrata una serie d’immagini che sintetizzano lo schema precedente. Le immagini mostrate fanno riferimento alla mia installazione di Eclipse PDT 2.2 + Eclox 0.8.0 + Doxygen 1.7 su piattaforma Mac OS X 10.6 Snow Leopard. Il processo resta comunque valido per tutte le altre piattaforme operative.

Figura 2 Avanzamento del processo d’installazione del plugin Eclox.

Figura 3 Configurazione del path d’installazione di Doxygen.

Figura 4 Creazione Doxyfile dal menù File -> New -> Doxyfile.

Figura 5 Interfaccia (basic mode) per l’editing del Doxyfile.

L’interfaccia in basic mode mostrata in Figura 5 è pressoché simile alla Doxygen GUI nativa installata con Doxygen, vedi il precedente articolo Doxygen for Mac OS X in Action.

Figura 6 Interfaccia (advanced mode) per l’editing del Doxyfile.

L’interfaccia in advanced mode consente di aver accesso a tutti i parametri di configurazione per il motore di Doxygen, modalità utile per alcuni utilizzi particolari, come per esempio la personalizzazione dei CSS per l’output in formato HTML. Per i più “smanettoni” è possibile visualizzare il sorgente del Doxyfile generato attraverso la GUI, basta aprire il file con l’editor di testo (vedi Figura 7).

Figura 7 Doxyfile aperto con il semplice editor di testo di Eclipse.

Figura 8 Esecuzione del comando per la generazione della documentazione.

Il comando Build Documentation del menù contestuale avvia Doxygen sulla base della configurazione impostata in precedenza (Doxyfile). La progressione del processo di creazione della documentazione è mostrata sulla Console di Eclipse (vedi Figura 9).

Figura 9 Output in console di Doxygen durante la fase di elaborazione del codice sorgente.

Nelle successive illustrazioni (Figura 10, Figura 11 e Figura 12) è possibile verificare il risultato ottenuto dal processo di generazione della documentazione. HTML e Man sono i formati di output richiesti in fase di configurazione. Sono da notare le versioni localizzate della documentazione per entrambi i formati.

Figura 10 Risultato del processo di creazione della documentazione in formato HTML.

Figura 11 Esempio di ricerca Ajax sulla documentazione del progetto.

Figura 12 Risultato del processo di creazione della documentazione in formato Man.

E’ vero che Eclox da circa un anno non è più manutenuto, ritengo comunque che può essere un valido strumento a supporto degli sviluppatori che devono utilizzare Doxygen per produrre la documentazione del proprio codice sorgente.