programming:php-and-doxygen

Commentare e documentare con stile grazie a Doxygen

Con questo articolo affronteremo un'argomento che è un pò ostico per molti programmatori: commentare il proprio codice sorgente.

Avere un codice ben commentato non solo facilita coloro che mettono mani ad un progetto già avvitato ma aiuta anche in fase di debug per capire perchè abbiamo scritto quella determinata funzione ed aiuta in fase coding in quanto oggigiorno la stragrande maggioranza degli IDE supporta l'autocompletamento del codice e commentare correttamente il codice ci aiuta anche per capire il tipo di valore che restituisce una funzione o che tipo di argomenti servono, senza la necessità aprire il sorgente che contiene il codice.

Doxygen

Doxygen è un applicazione multipiattaforma (Windows, Linux, MacOSX, etc.) che permette di creare documentazione partendo dal nostro codice sorgente (C, C++, Perl, Python, PHP, Java, etc.) in diversi formati (man pages, HTML, PDF, CHM, 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) di relazioni tra classi e strutture.

Esempio di codice commentato

Di seguito un esempio di classe che utilizza alcuni dei comandi di Doxygen. 

<?php
/**
 * Foo Class
 * 
 * Description of foo class
 * 
 * @package    MyCMS.Foo
 * @author     John Doe <[email protected]>
 * @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;
  }
 
}

Comandi più utilizzati

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 <[email protected]>
 * @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
@version <versione-del-codice> Specifica la versione del codice 
/**
 * @version    1.0.1
 * @since      0.9.5
 */
@since <versione-del-codice> Indica da quale vesione esiste una determinata funzione o metodo

Documentiamo

Il successivo passo dopo aver commentato il nostro codice è creare una documentazione.

Prima di tutto creiamo un file di configurazione generico: 

$ doxygen -g <config-file>

Successivamente è necessario personalizzare la configurazione appena prodotto in base ai nostri gusti. In particolare dobbiamo specificare il nome del progetto (PROJECT_NAME), la directory contenente il nostro codice (INPUT_DIR), la directory dove salveremo la documentazione (OUTPUT_DIR), il linguaggio di programmazione (es OPTIMIZE_FOR_C).

Per chi non vuole sporcarsi le mani tra le centinaia di opzioni disponibili, Doxygen mette a disposizione una GUI che facilita questo compito. 

$ doxywizard <config-file>

Come ultimo passo lanciamo la generazione della documentazione: 

$ doxygen <config-file>

Configurazioni utili per codice in PHP

Per documentare il nostro codice PHP è necessario utilizzare l'opzione OPTIMIZE_FOR_C: 

OPTIMIZE_FOR_C = YES

Grazie all'opzione INPUT_FILTER andremo a corregge un piccolo problema relativo al comando @var. 

INPUT_FILTER = php php_var_filter.php

Scarichiamo il file qui sotto e lo copiamo nella stessa directory del file di configurazione di Doxygen:

php_var_filter.php
/**
 * FIX "@var" annotation for Doxygen
 *
 * @fixme  static property
 * @see  http://stackoverflow.com/a/8472180
 * @see  https://bugzilla.gnome.org/show_bug.cgi?id=626105
 */
 
$source = file_get_contents($argv[1]);
 
$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
$replac = '${2} */ ${3} ${1} ${4}';
$source = preg_replace($regexp, $replac, $source);
 
echo $source;

Come output consiglio l'HTML in quanto permette la navigazione ipertestuale oltre alla possibilità di utilizzare il motore di ricerca interno per ricercare una funzione o metodo specifico. 

GENERATE_HTML = YES

Per maggiori informazioni

, , ,
  • programming/php-and-doxygen.txt
  • Last modified: 10 years ago
  • by Giuseppe Di Terlizzi