L'idea alla base di una libreria di classi è quella dell'evoluzione nel tempo: alcuni metodi vengono aggiunti, altri modificati o eliminati. Anche la documentazione deve poter tenere traccia delle modifiche in relazione alle versioni del progetto.
Il primo tag di questo tipo da considerare è @version che permette di indicare le versioni di singole parti ma è consigliabile utilizzarlo per intere librerie, documentando interi file. Per semplificare tale task è possibile riferirsi a variabili del sistema di versioning che verranno rimpiazzate con la versione corrente dal software usato per generare la documentazione.
Per ottenere questo effetto è necessario usare i vettori nella forma nome-del-sistema-di-versioning: $vettore$. Ad esempio per ottenere la versione da un repository GIT la sintassi diventa:
/*
* @version GIT: $Id$
*/
@since indica invece la prima versione della libreria in cui è apparsa la funzionalità a cui si riferisce (una classe, una costante o un metodo). E' possibile inserire per lo stesso elemento commentato più di un tag @since con cui illustrare, ad esempio, le modifiche dell'interfaccia. In questo modo con l'ultima versione della documentazione si può avere un'idea di cosa è disponibile in una release precedente.
Eliminare un metodo da un'interfaccia pubblica non è mai una soluzione facile perché introduce incompatibilità con i software che adottavano versioni precedenti, si consiglia quindi di dichiarare come deprecato il metodo, mantenerlo così fino alla prossima major release e solo dopo eliminarlo.
Dichiarare un metodo deprecato equivale a dire "continua ad usarlo a tuo rischio e pericolo, in una prossima versione verrà eliminato". Per questi casi è possibile usare il tag @deprecated indicando facoltativamente la prima versione in cui non sarà più presente ed inserendo un'eventuale descrizione che specifica i motivi dell'indicazione o le alternative preferibili.
Riferimenti esterni
Data l'ereditarietà dell'OOP possono ricorrere casi in cui la documentazione di un metodo della classe figlia è uguale a quello della classe parent, anche se quest'ultimo è stato sovrascritto. In tali casi una soluzione potrebbe essere copiare il DocBlock della classe padre al posto di quello della classe figlia, in modo che la documentazione generata contenga anche tali informazioni. Vi è però la necessità di aggiornare periodicamente la versione copiata con il rischio di perdere alcune modifiche nella documentazione.
Per questo motivo è possibile usare il tag @inheritDoc con cui indicare un riferimento all'elemento corrispondente della classe padre. La sintassi in questo caso l'elemento deve essere inserito come tag inline, circondato da parentesi graffe:
/*
* {@inheritDoc}
*/Benché nella maggior parte dei casi questa sintassi preveda il tag come unico elemento nel DocBlock, in maniera facoltativa è possibile aggiungere un'ulteriore descrizione da riferire esclusivamente al metodo della classe figlia. In questo modo è possibile ad esempio dettagliare un funzionamento particolare pur mantenendo la stessa interfaccia, senza doverla ridefinire.
Quando il riferimento è invece ad un elemento diverso, è possibile usare il tag @see che richiede come parametro obbligatorio il nome del metodo o della proprietà a cui riferirsi con la notazione tipica delle chiamate statiche (nome della classe, doppio carattere ":" e nome della proprietà o del metodo).
In alternativa, lo stesso tag può essere usato anche per indicare un riferimento ad una pagina web dove mostrare il funzionamento con un esempio concreto o un tutorial; in questo caso l'URL deve essere indicato ovviamente come assoluto. Entrambi gli utilizzi del tag consentono un terzo parametro per specificare il motivo del riferimento.
Per indicare un esempio esiste un tag ancora più indicato: @example; la sintassi è la stessa di @see utilizzato con URL esterno e una descrizione aggiuntiva.
Tag vs. Annotazioni
Da alcuni anni si è diffuso anche per varie librerie PHP il concetto di annotazione, la libreria Doctrine e il framework Symfony ne fanno ad esempio un uso massiccio.
Un'annotazione è un'indicazione inserita in un commento, nel caso di PHP all'interno di un DocBlock, con cui aggiungere una funzionalità (funzione, metodo o classe) ad un blocco di codice. Questo pattern è più comune in linguaggi di programmazione che devono passare per un compilatore o uno pseudo compilatore, e il vantaggio principale consiste nel rendere il corpo di una funzione più asciutto, limitandolo al codice utile e nascondendo le parti ripetitive. Concettualmente un'annotazione può essere considerata come una decorazione.
Il problema principale risiede nel fatto che le annotazioni in PHP hanno la stessa forma dei tag di PHPDoc, quindi è possibile che un software (o un IDE) restituisca un errore non riconoscendo i tag. Per questo motivo ogni annotazione deve avere come prefisso il namespace a cui si riferisce, relativo alla libreria da cui dipende.
Generare la documentazione
Vista la diffusione di PHP oggi esistono diversi framework di testing o generatori di documentazione open source. Tra questi il primo a raggiungere una forma matura è stato phpDocumentor usato da Zend Framework, PropelOrm ed eZ publish. Sono poi nati altri progetti come Sami, usato da Symfony o ApiGen, Doctrine e CakePHP.
I tag supportati sono sostanzialmente gli stessi, a maggior ragione ora che PHPDoc si sta avviando a diventare un possibile PSR. La differenza principale tra i vari software è data dal formato dell'esecuzione, in genere personalizzabile tramite template.
Di base questi progetti generano file HTML statici da caricare per la consultazione, la generazione della documentazione per un progetto di grandi dimensioni può quindi richiedere qualche minuto. In genere i template, pur variando nell'aspetto, mantengono una struttura simile con una colonna contenente l'elenco dei namespace e delle classi presenti in ordine gerarchico, al click sul nome di una classe viene visualizzata la documentazione creata.