This is an old revision of the document!


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 correttamente il codice ci aiuta anche per capire cosa fa un determinato metodo e che argomenti servono, senza la necessità aprire il sorgente 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 partendo dal codice sorgente (C, C++, Perl, Python, PHP, Java, etc.) in diversi formati (man pages, HTML, PDF, CHM, RTF, LaTex, PostScript, 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.1405378529.txt.gz
  • Last modified: 6 years ago
  • (external edit)