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.

1. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
PHP
Documentation
APIs
on
the
fly
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
tools1.
Nel
corso
di
questo
breve
articolo
vedremo
come
generare
on
the
fly
la
documentazione
delle
API
di
un
progetto
scritto
in
PHP2;
potremmo
per
esempio
prendere
in
considerazione
il
progetto
Open
Source
Wordpress3
e
di
questo
generare
la
documentazione
delle
API4.
Assumiamo
che:
• L’ambiente
di
sviluppo
sia
Eclipse
PDT
Helios5;
• 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.
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/
11/01/11
1
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

2. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
1
Menu
di
accesso
alla
funzione
di
creazione
e
configurazione
External
Tools.
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.
11/01/11
2
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

3. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
3
External
Tools
Wordpress
API
Docs
aggiunto
alla
lista
dopo
la
creazione.
Figura
4
Wordpress
API
Docs
in
action.
11/01/11
3
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

4. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
5
TreeView
documentazione
API.
Figura
6
Home
Page
della
documentazione
delle
API.
11/01/11
4
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike

5. Antonio
Musarra's
Blog
The
ideal
solution
for
a
problem
Blog:
http://musarra.wordpress.com
Mail:
antonio.musarra@gmail.com
Figura
7
Documentazione
di
dettaglio
su
di
una
classe
parte
delle
API.
11/01/11
5
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike