Eclox Doxygen Plugin for Eclipse

  • Figura 3 Configurazione del path d’installazione di Doxygen.
    Figura 3 Configurazione del path d’installazione di Doxygen.
  • Figura 4 Creazione Doxyfile dal menù File -> New -> Doxyfile.
    Figura 4 Creazione Doxyfile dal menù File -> New -> Doxyfile.
  • Figura 10 Risultato del processo di creazione della documentazione in formato HTML.
    Figura 10 Risultato del processo di creazione della documentazione in formato HTML.
  • Figura 11 Esempio di ricerca Ajax sulla documentazione del progetto.
    Figura 11 Esempio di ricerca Ajax sulla documentazione del progetto.
  • Figura 12 Risultato del processo di creazione della documentazione in formato Man.
    Figura 12 Risultato del processo di creazione della documentazione in formato Man.
  • Figura 5 Interfaccia (basic mode) per l’editing del Doxyfile.
    Figura 5 Interfaccia (basic mode) per l’editing del Doxyfile.
  • Figura 6 Interfaccia (advanced mode) per l’editing del Doxyfile.
    Figura 6 Interfaccia (advanced mode) per l’editing del Doxyfile.
  • Figura 7 Doxyfile aperto con il semplice editor di testo di Eclipse.
    Figura 7 Doxyfile aperto con il semplice editor di testo di Eclipse.
  • Figura 2 Avanzamento del processo d’installazione del plugin Eclox.
    Figura 2 Avanzamento del processo d’installazione del plugin Eclox.
  • Figura 8 Esecuzione del comando per la generazione della documentazione.
    Figura 8 Esecuzione del comando per la generazione della documentazione.
  • Figura 9 Output in console di Doxygen durante la fase di elaborazione del codice sorgente.
    Figura 9 Output in console di Doxygen durante la fase di elaborazione del codice sorgente.
  • Figura 1 Schema funzionale del plugin Eclox.
    Figura 1 Schema funzionale del plugin Eclox.

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.

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 2 Avanzamento del processo d’installazione del plugin Eclox.

Figura 3 Configurazione del path d’installazione di Doxygen.

Figura 3 Configurazione del path d’installazione di Doxygen.

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

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

Figura 5 Interfaccia (basic mode) per l’editing del 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.

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 7 Doxyfile aperto con il semplice editor di testo di Eclipse.

Figura 8 Esecuzione del comando per la generazione della documentazione.

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.

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 10 Risultato del processo di creazione della documentazione in formato HTML.

Figura 11 Esempio di ricerca Ajax sulla documentazione del progetto.

Figura 11 Esempio di ricerca Ajax sulla documentazione del progetto.

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

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.


[1] Eclipse è un ambiente di sviluppo integrato multi-linguaggio e multipiattaforma. Ideato da un consorzio di grandi società quali Ericsson, HP, IBM, Intel, MontaVista Software, QNX, SAP e Serena Software, chiamato Eclipse Foundation, viene sviluppato da una comunità strutturata sullo stile dell’open source. Ulteriori informazione sul sito ufficiale all’indirizzo http://www.eclipse.org

Antonio Musarra

I began my journey into the world of computing from an Olivetti M24 PC (http://it.wikipedia.org/wiki/Olivetti_M24) bought by my father for his work. Day after day, quickly taking control until … Now doing business consulting for projects in the enterprise application development using web-oriented technologies such as J2EE, Web Services, ESB, TIBCO, PHP.

Potrebbero interessarti anche...