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

Ora che tutto è installato e configurato, come spiegato nella parte 1 di questo tutorial, come fare per ottenere la documentazione API del nostro software scritto in PHP.

ApiGen, come altri sistemi automatici per la produzione della documentazione dei sorgenti software, fa uso dei commenti inseriti nel codice sorgente per compilare la documentazione.
Perché un commento sia inserito nella documentazione è necessario che inizi con il tag di apertura del commento immediatamente seguito da un secondo asterisco /**.

NetBeans conosce bene questo stile dal tool JavaDoc. E ne fa uso anche all'interno dell'IDE stesso.   Non appena si preme <invio> dopo il secondo asterisco,  è automaticamente predisposto uno scheletro in base a ciò che segue il commento.

Commento di base predisposto automaticamente da NetBeans

Ad esempio, nella finestra precedente, subito dopo aver premuto invio, NetBeans ha parzialmente completato la documentazione individuando il parametro della funzione, il tipo del parametro (potrebbe uscire scritto type, nel qual caso va inserito a mano), il valore ritornato dalla funzione (l'oggetto di classe UTF8char) e il tipo di possibile eccezione sollevata.

Un commento descrittivo può essere posto in cima. Il commento può contenere codice ed entità HTML. Dal Config.php di ApiGen risultano permessi i tag b, i, a, ul, ol, li, p, br, var, samp, kbd, tt.

Autocompletamento all'interno dei commenti

Il carattere @ è una carattere di escape con cui si indica che ciò che segue va interpretato in modo particolare da parte del generatore della documentazione. Ad esempio, nell'immagine precedente, Netbeans ha utilizzato @param per specificare il parametro, @return per specificare il tipo di dato ritornato dalla funzione e @throws per specificare il tipo di eccezione sollevabile dalla funzione.

I possibili elementi (annotazioni) sono tanti, ed è possibile visualizzarli inserendo @ all'interno della sezione di commento e lasciando apparire l'auto-completamento (CTRL+Spazio se non appare spontaneamente) come nella figura accanto.

Scorrendo la lista NetBeans mostra, per ogni possibile annotazione, un help che spiega come utilizzarla con piccoli esempi.

Volendo quindi completare il commento per il metodo come nell'esempio seguente

/**
 * Funzione di creazione di un oggetto a partire dal relativo
 * codice {@link http://www.unicode.org UNICODE}
 *
 * Esempio:
 * <code>
 * $charObj = UTF8Char::getUTF8CharFromInt(65);
 * </code>
 *
 * @param int <p>Valore decimale Unicode del carattere di cui produrre la codifica UTF-8</p>
 * @return \CiP\UTF8Char L'oggetto UTF8Char risultante
 * @throws \Exception
 * <p>Sono sollevate delle eccezzioni nel caso in cui:
 *     <ul>
 *         <li>Sia fornito un valore minore di 0</li>
 *         <li>Il valore numerico fornito richieda più di 4 byte per essere codificato in UTF-8</li>  *     </lu>
 * </p>    
 */

otterremo come dettaglio di produzione della documentazione con ApiGen per il metodo la pagina web mostrata nell'immagine seguente.

Il dettaglio della documentazione prodotta il metodo statico getUFT8CharFromInt

Come dicevo prima, NetBeans fa uso di questi commenti anche all'interno dell'IDE. Se proviamo a scrivere il codice per invocare il metodo, l'auto-completamento non solo ci propone il metodo, ma mostra anche un help con le informazioni presenti nel commento al metodo come mostrato nell'immagine seguente.

Il commento al metodo utilizzato come help dall'IDE NetBeans