PHP Documentation APIs on the fly

  • External Tools Wordpress API Docs aggiunto alla lista dopo la creazione.
  • Menu di accesso alla funzione di creazione e configurazione External Tools.
  • Creazione dell’External Tools Wordpress API Docs.
  • Wordpress API Docs in action.
  • TreeView documentazione API.
  • Home Page della documentazione delle API.
  • Documentazione di dettaglio su di una classe parte delle API.

All’interno del ciclo di vita di un progetto software reputo importante la percentuale di tempo dedicata a redigere la documentazione di progetto, a volte, anzi direi molto di frequente la percentuale di tempo dedicata a quest’attività, è intorno allo zero.

La documentazione che accompagna un progetto software è di vario tipo, per esperienza personale ritengo che una buona documentazione delle API sia una cosa gradita soprattutto ai “posteri” che in futuro dovranno utilizzare o estendere il progetto software.

Non ho nessuna remora nell’affermare che la documentazione delle API si scrive da sola, nello stesso istante dedicato alla scrittura del codice sorgente. Redigere la documentazione mentre si scrive il codice, è molto semplice, ciò è reso possibile grazie a particolari annotazioni e tools[1].

Nel corso di questo breve articolo vedremo come generare on the fly la documentazione delle API di un progetto scritto in PHP[2]; potremmo per esempio prendere in considerazione il progetto Open Source WordPress[3] e di questo generare la documentazione delle API[4]. Assumiamo che:

  • L’ambiente di sviluppo sia Eclipse PDT Helios[5];
  • Il progetto WordPress sia presente nel proprio workspace Eclipse;
  • Sul sistema sia installato e correttamente configurato il tool PHPDoc.

Il progetto WordPress può essere creato sul proprio workspace Eclipse direttamente dal repository SVN pubblico di wordpress.org. Tutte le informazioni necessarie sono disponibili all’indirizzo http://wordpress.org/download/svn/ .

Il “trucco dell’on the fly” è abbastanza semplice, basta configurare su Eclipse PDT Helios un cosiddetto External Tools, che nel nostro caso chiamerà il tool PHPDoc passando opportuni parametri. L’External Tool che andremo a creare prenderà il nome di WordPress API Docs. E’ talmente semplice la procedura di creazione dell’External Tools che ho preferito utilizzare delle illustrazioni con opportune indicazioni. Nelle figure che seguono, sono quindi illustrati i passi necessari alla creazione del comando per generare il documento delle API.

Menu di accesso alla funzione di creazione e configurazione External Tools.

Figura 1 Menu di accesso alla funzione di creazione e configurazione External Tools.

Creazione dell’External Tools WordPress API Docs.

Figura 2 Creazione dell’External Tools WordPress API Docs.

Il box Arguments (sezione numero quattro) della Figura 2 indica quali parametri da passare al comando phpdoc, in particolare, il parametro –d imposta il folder contenente il codice sorgente da cui generare la documentazione delle API, e il valore assegnato (${folder_prompt}) fa sì che sia l’utente a scegliere il folder.

External Tools WordPress API Docs aggiunto alla lista dopo la creazione.

Figura 3 External Tools WordPress API Docs aggiunto alla lista dopo la creazione.

Wordpress API Docs in action.

Figura 4 WordPress API Docs in action.

TreeView documentazione API.

Figura 5 TreeView documentazione API.

Home Page della documentazione delle API.

Figura 6 Home Page della documentazione delle API.

Documentazione di dettaglio su di una classe parte delle API.

Figura 7 Documentazione di dettaglio su di una classe parte delle API.


[1] Analizzano il codice sorgente e generano la documentazione in vari formati di output (HTML, PDF, DocBook, etc…). JavaDoc, PHPDoc, Doxygen, etc… sono alcuni di questi.

[2] PHP (acronimo ricorsivo di “PHP: Hypertext Preprocessor”, preprocessore d’ipertesti) è un linguaggio di scripting interpretato, con licenza open source e libera (ma incompatibile con la GPL), originariamente concepito per la programmazione Web ovvero la realizzazione di pagine web dinamiche.

[3] E’ una piattaforma di “personal publishing” e content management system (CMS), scritta in PHP e che usa come database MySQL. Creata da Matt Mullenweg, è distribuita con la licenza GNU General Public License.

[4] Le Application Programming Interface API (Interfaccia di Programmazione di un’Applicazione), sono ogni insieme di procedure disponibili al programmatore, di solito raggruppate a formare un set di strumenti specifici per un determinato compito. È un metodo per ottenere un’astrazione, di solito tra l’hardware e il programmatore, o tra software a basso ed alto livello. Le API permettono di evitare ai programmatori di scrivere tutte le funzioni dal nulla. Le API stesse sono un’astrazione: il software che fornisce una certa API è detto che implementa le API.

[5] L’IDE Eclipse dedicato all’ambiente di sviluppo PHP. Per maggiori informazioni consultare il sito http://www.eclipse.org/pdt/

0 Condivisioni

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