Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
programming:php-and-doxygen [2014/07/15 08:52]
Giuseppe Di Terlizzi [Documentiamo]
programming:php-and-doxygen [2014/07/15 11:07]
Giuseppe Di Terlizzi
Line 1: Line 1:
 ====== Commentare e documentare con stile grazie a Doxygen ====== ====== 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.+Con questo articolo affronteremo un'argomento che è un pò ostico per molti 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 capire cosa fa una determinata funzione o metodo.+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.
  
-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.+===== Doxygen =====
  
-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 nostro codice sorgente (C, C++, Perl, Python, PHP, Java, etc.) in diversi formati (man pages, HTML, PDF, CHM, LaTex, PostScript, etc...).
- +
-===== Doxygen =====+
  
-**Doxygen** è un applicazione multipiattaforma (WindowsLinux, 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**di relazioni tra classi e strutture.
  
-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. 
  
-==== Un esempio ====+==== Esempio di codice commentato ====
  
-Di seguito un esempio di classe che utilizza i principali comandi di **Doxygen**.+Di seguito un esempio di classe che utilizza alcuni dei comandi di **Doxygen**.
  
 <code .php> <code .php>
Line 60: Line 57:
 } }
 </code> </code>
 +
  
 ==== Comandi più utilizzati ==== ==== Comandi più utilizzati ====
Line 100: Line 98:
 | ''@copyright <copyright>'' | Specifica il copyright del codice | ::: | | ''@copyright <copyright>'' | Specifica il copyright del codice | ::: |
 | ''@license <licensa>'' | Specifica la licenza utilizzata per il codice | ::: | | ''@license <licensa>'' | Specifica la licenza utilizzata per il codice | ::: |
 +| ''@version <versione-del-codice>'' | Specifica la versione del codice | <code .php>/**
 + * @version    1.0.1
 + * @since      0.9.5
 + */</code> |
 +| ''@since <versione-del-codice>'' | Indica da quale vesione esiste una determinata funzione o metodo | ::: |
 +
  
 ==== Documentiamo ==== ==== Documentiamo ====
  
-Il successivo passo è creare una documentazione del proprio codice.+Il successivo passo dopo aver commentato il nostro codice è creare una documentazione.
  
 Prima di tutto creiamo un file di configurazione generico: Prima di tutto creiamo un file di configurazione generico:
Line 109: Line 113:
   $ doxygen -g <config-file>   $ doxygen -g <config-file>
      
-Successivamente è necessario personalizzare la configurazione di Doxygen in base ai nostri gusti. In particolare dobbiamo specificare il nome del progetto, la directory contenente il nostro codice, il linguaggio di programmazione.+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'').
  
-<div info round center 80%>Per chi non vuole sporcarsi le mani tra centinaia di flagDoxgen mette a disposizione una GUI che facilita questo compito.+<div info round center 80%>Per chi non vuole sporcarsi le mani tra le centinaia di opzioni disponibiliDoxygen mette a disposizione una GUI che facilita questo compito.
  
   $ doxywizard <config-file>   $ doxywizard <config-file>
Line 120: Line 124:
   $ doxygen <config-file>   $ doxygen <config-file>
  
-===== Maggiori informazioni =====+   
 +==== 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: 
 + 
 +<file .php 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; 
 +</file> 
 + 
 +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 =====
   * Doxygen - http://www.stack.nl/~dimitri/doxygen/   * Doxygen - http://www.stack.nl/~dimitri/doxygen/
   * Graphviz - http://graphviz.org/   * Graphviz - http://graphviz.org/
  
 {{tag>programming php doxygen graphviz}} {{tag>programming php doxygen graphviz}}
  • programming/php-and-doxygen.txt
  • Last modified: 6 years ago
  • by Giuseppe Di Terlizzi