This is an old revision of the document!


Commentare e documentare con stile grazie a 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 Graphviz) con le relazioni tra classi e strutture.

Di seguito un esempio di classe che utilizza i principali comandi di Doxygen.

<?php
/**
 * Foo Class
 * 
 * Description of foo class
 * 
 * @package    MyCMS.Foo
 * @author     John Doe <john.doe@example.com>
 * @copyright  (C)2014, John Doe
 * @license    see LICENSE.txt
 */
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()
 */
@author <nome> <email> Indica l'autore del codice e l'indirizzo e-mail
/**
 * @author     John Doe <john.doe@example.com>
 * @copyright  (C)2014, John Doe
 * @license    See LICENSE.txt
 */
@copyright <copyright> Specifica il copyright del codice
@license <licensa> Specifica la licenza utilizzata per il codice

Il successivo passo è creare una documentazione del proprio codice.

Prima di tutto creiamo un file do configurazione generico per Doxygen:

$ doxygen -g <config-file>

Il prossimo passo è personalizzare la configurazione di Doxygen in base ai nostri gusti. Come ultimo passo lanciamo la generazione della documentazione:

$ doxygen <config-file>
  • programming/php-and-doxygen.1405379356.txt.gz
  • Last modified: 10 years ago
  • (external edit)