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/

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.

You may also like...

Cos'è il progetto CIE/CNS Apache Docker - Developers Italia

In questo video https://youtu.be/TcAzn1POhsM introdurrò il progetto CIE/CNS Apache Docker di Developers Italia (https://developers.italia.it/it/cie/#resourcecontent-3) nato circa due anni fa.

L'obiettivo di questo progetto è quello di fornire un template pronto all'uso che realizza un sistema di autenticazione tramite la Smart Card TS-CNS (o CNS) e la CIE (Carta d'Identità Elettronica) basato su Apache HTTP. Ognuno può poi modificare o specializzare questo progetto sulla base delle proprie esigenze Si tratta di un progetto docker per la creazione di un container che implementa un sistema di mutua autenticazione o autenticazione bilaterale SSL/TLS.

Questo meccanismo di autenticazione richiede anche il certificato digitale da parte del client, certificato che in questo caso risiede all'interno della TS-CNS o della CIE. La particolarità del sistema implementato (attraverso questo container) è quella di consentire l'autenticazione tramite:

  • La TS-CNS (Tessera Sanitaria - Carta Nazionale Servizi), rilasciata dalla regione di appartenenza;
  • La CIE (Carta d'Identità Elettronica), rilasciata dal comune di residenza.

Nella versione 2.0.0 il progetto è stato aggiornato per essere uniforme alle linee guida di Bootstrap Italia. A seguire alcune risorse che possono essere utili.

  • Cos’è il progetto CIE/CNS Apache Docker (http://bit.ly/3aJ5Gbl)
  • CIE Carta d'Identità Elettronica (https://developers.italia.it/it/cie/)
  • Carta Nazionale dei Servizi (https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi)
  • Raspberry Pi – Un esempio di applicazione della TS-CNS (https://bit.ly/3hkJ8Aj)
  • Pubblicare il servizio CIE/CNS Apache Docker su Azure Cloud (http://bit.ly/3aPoq8V)
  • Come accedere al portale VETINFO tramite TS-CNS e Mac OS (http://bit.ly/2VFMKq7)