PHPDOC, questo sconosciuto

Non molti conoscono la potenza di PHPDOC, il linguaggio di documentazione tecnica, derivato da JAVADOC, da utilizzare negli applicativi PHP.

Esso presenta molti costrutti che ci aiutano nell'interpretazione di classi, metodi e funzioni presenti nella nostra codebase:


/**
* Returns the birthday of the user.
*
* @param boolean $asDateTime
* @return string|DateTime
* @throws Exception
*/
public function getBirthdate($asDateTime = false)
{
...


Il PHPDOC è in genere fondamentale quando si lavora in team, e buona pratica anche per il lavoro solitario, per non dover perdere del tempo a demistificare una data scelta di design, sapere quale eccezione può venire lanciata da un metodo e così via.

A parte il vostro fidato IDE, ci sono almeno 3 strumenti per poter generare la documentazione di un progetto PHP mediante PHPDOC:

• phpDocumentor, vetusto software risalente ai fasti di PHP4, oramai utilizzato pochissimo per via del suo ciclo di sviluppo abbandonato a sè stesso ( non è compatibile con PHP 5.3, ad esempio )
• doxygen, software sicuramente più maturo e supportato, non direttamente scritto in PHP, disponibili sulle distribuzioni Debian-derived tramite apt-get
• docblox, il più giovane tra i progetti citati, PHP 5.3-compliant, scritto nativamente in PHP e già  usato dallo Zend Framework