This is an old revision of the document!


PHP: Commentare con stile con Doxygen

Con questo articolo affronteremo un'argomento che è la gioia e dolore dei programmatori: commentare il proprio codice sorgente.

Commentare il nostro codice sorgente non solo ci facilita la vita durante il debug del codice ma ci aiuta a capire cosa fa una determinata funzione o metodo.

Inoltre commentare correttamente il codice ci aiuta anche in fase di coding. Oggigiorno la stragrande maggioranza degli IDE supporta l'autocompletamento del codice e commentare il codice ci aiuta anche per capire cosa fa un determinato metodo e che argomenti servono, senza che è necessario aprire il file che contiene il codice.

Un utilissimo tool che ci aiuta in questa cruciale fase è Doxygen.

Doxygen è un applicazione multipiattaforma (Windows, Linux, MacOSX, etc.) che permette di creare documentazione dal codice sorgente (C, C++, Perl, Python, PHP, Java, etc.).

Grazie all'utilizzo di particolari “comandi” inseriti nel codice sorgente permette di creare una documentazione accurata del nostro codice con tanto di grafici (grazie a Graphziz) con le relazioni tra classi e strutture.

<?php
 
class Foo {
 
  /**
   * Things
   * 
   * @var  array
   */
  private $_data = array();
 
  /**
   * Constructor
   * 
   * @param  array  $things
   */
  public function __construct($thighs = array()) {
    $this->_data = $things;
  }
 
  /**
   * Get data
   * 
   * @return  array
   */
  public function getData() {
    return $this->_data;
  }
 
}
Comando Descrizione Esempio
@var <tipo> Indica la dichiarazione di una variabile
/**
 * Description
 * 
 * @var  string|array
 */
public $data = array();
@param <tipo> <argomento> <descrizione> Dichiara un argomento di una funzione o metodo
/**
 * Description of function|method
 * 
 * @param  array  $things  Description
 * @return  boolean  Description
 */
function my_func($things) {
  // ...
  return true;
}
@return <tipo> <descrizione> Dichiara il valore restituito da una funzione o metodo
@code@endcode Crea una sezione che mostra un esempio di codice
/**
 * @code
   $my_class = new MyClass;
   $my_class->foo('bar');
   @endcode
 */
@see <link> Indica un link ad una risorsa, una classe, metodo o funzione
/**
 * @see  http://example.org
 * @see  substr()
 * @see  MyClass::myMethod()
 */
  • programming/php-and-doxygen.1405378203.txt.gz
  • Last modified: 6 years ago
  • (external edit)