martedì 26 marzo 2013

NetBeans e ApiGen: Documentare il codice PHP (Parte 1/2)

Fra le tante schede presenti fra le opzioni di NetBeans dedicate al PHP, c'è una dedicata ad ApiGen. ApiGen è un tool per la produzione di documentazione relativa ai progetti PHP partendo dall'analisi dei sorgenti. La sua integrazione in NetBeans lo rende uno strumento comodo e di semplice utilizzo per la generazione automatica della documentazione API.

Per mettere in funzione ApiGen in NetBeans, andare sul sito apigen.org e scaricare l'ultima versione disponibile facendo clic sul grande pulsante blu "Download ApiGen".
La pagina internet di ApiGen
Sebbene ApiGen sia installabile tramite PEAR (che consente di tenerlo aggiornato), per comodità scarichiamo la versione standalone.

Terminato il download dell'archivio zip, scompattare il contenuto in una posizione di propria scelta. Ad esempio io per comodità l'ho messo nella cartella di installazione di xampp.
Il contenuto dell'archivio zip scompattato nella cartella di xampp
Avviare NetBeans, quindi cliccare la voce Options del menu Tools. Cliccare su PHP, quindi sulla scheda ApiGen.
La scheda ApiGen nelle PHP Options di NetBeans
Fare clic sul tasto Browse... e, dalla finestra di selezione file che si apre, andare a selezionare il file apigen.bat che si trova all'interno della cartella apigen precedentemente decompressa.

Fatto!!! ApiGen è pronto a funzionare.

Per generare la documentazione relativa ad un progetto PHP sviluppato in NetBeans, basta fare clic con il tasto destro del mouse sul progetto da documentare, nella scheda Projects, e fare clic sulla voce Generate Documentation come mostrato nella finestra sottostante. Se è la prima documentazione che produciamo per il progetto, appare una finestra che ci chiede dove salvare i file generati. Selezionata la cartella di destinazione, la generazione della documentazione procede.
Esempio di avvio della generazione della documentazione

Nella finestra di output di NetBeans appaiono le informazioni sulle attività in fase di svolgimento da parte di ApiGen. Alla fine, se la documentazione è prodotta in modo corretto, è aperto il browser sulla pagina index della documentazione appena prodotta.
Esempio di documentazione prodotta su un mio progetto di test per caratteri UTF-8
Per personalizzare eventuali proprietà di generazione della documentazione per il progetto, fare clic con il tasto destro del mouse sul nome del progetto nella scheda Projects e scegliere Properties dal menu contestuale. Nella finestra di dialogo fare clic sulla categoria ApiGen.
Le proprietà ApiGen per il progetto
Potremo così personalizzare i vari elementi coinvolti nella generazione della documentazione. Un esempio di come fare in modo che il codice sorgente integri al suo interno la documentazione lo vedremo nel prossimo post.

Nessun commento: