Doxygen

Doxygen è una applicazione per la generazione automatica della documentazione a partire dal codice sorgente di un generico software. È un progetto open source disponibile sotto licenza GPL, scritto per la maggior parte da Dimitri van Heesch a partire dal 1997.

Doxygen software
Logo
Schermata di esempio
Genere	Sistema di documentazione (non in lista)
Sviluppatore	Dimitri van Heesch
Data prima versione	26 ottobre 1997
Ultima versione	1.10.0 (25 dicembre 2023)
Sistema operativo	Multipiattaforma
Linguaggio	C++
Toolkit	Qt
Licenza	GNU GPL v2 (licenza libera)
Sito web	www.doxygen.org/

Doxygen è un sistema multipiattaforma (Windows, Mac OS, Linux, ecc.) ed opera con i linguaggi C++, C, Java, Objective C, Python, IDL (versioni CORBA e Microsoft), Fortran, PHP, C#, e D. Nell'ambito del C++, è compatibile con le estensioni Qt.

È il sistema di documentazione di gran lunga più utilizzato nei grandi progetti open source in C++. Due esempi per tutti, sono l'adozione di doxygen da parte di ACE e KDE. In Java invece, la posizione leader viene meno, in virtù della presenza del concorrente Javadoc.

Il sistema estrae la documentazione dai commenti inseriti nel codice sorgente e dalla dichiarazione delle strutture dati.

La documentazione prodotta

Il risultato finale è disponibile sotto forma di pagine HTML oppure nei formati CHM, RTF, PDF, LaTeX, PostScript o man pages di Unix. Il formato HTML prodotto si giova di un sistema di hyperlink molto curato che permette al lettore un'agevole navigazione della struttura dei file sorgenti. La documentazione prodotta riporta anche il diagramma delle classi, nei casi in cui sono presenti relazioni di ereditarietà tra strutture dati. Grazie all'impiego sinergico di Doxygen con Graphviz, è possibile includere nella documentazione diagrammi delle classi per tutti gli altri tipi di relazioni tra strutture dati. I documenti possono essere generati in diverse lingue, tra cui è compreso l'italiano.

Infine, il sistema è altamente e facilmente configurabile al fine di permettere all'utilizzatore di intervenire su tutti gli aspetti della documentazione prodotta.

Il formato dei commenti

Il funzionamento di Doxygen richiede una particolare formattazione dei commenti inseriti nel codice sorgente. Le regole di formattazione, oltre ad essere analoghe a quelle degli altri prodotti della categoria, sono chiaramente documentate nel manuale. Riportiamo di seguito un esempio.

/**
 * The time class represents a moment of time.
 *
 * \author My Name
 */
class Time {

  /**
   * Constructor that sets the time to a given value.
   * \param timemillis Number of milliseconds passed since Jan 1. 1970
   */
  Time(int timemillis) {
    ...
  }

  /**
   * Get the current time.
   * \return A time object set to the current time.
   */
  static Time now() {
    ...
  }
};

Il file di configurazione

Doxygen associa ad ogni progetto da documentare un file di configurazione che contiene le impostazioni da utilizzare per la generazione. Questo file è un elenco di assegnazioni di opportuni valori a determinati parametri (TAG). Ogni tag è formato dalla coppia di informazioni

NOME_PARAMETRO = VALORE_PARAMETRO

analogamente a quanto avviene nei file di configurazione di numerosi altri prodotti open source. Un frammento di un esempio del file di configurazione è il seguente:

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
# by quotes) that should identify the project.

PROJECT_NAME           = MyProject

# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
# base path where the generated documentation will be put. 
# If a relative path is entered, it will be relative to the location 
# where doxygen was started. If left blank the current directory will be used.

OUTPUT_DIRECTORY       =

# The OUTPUT_LANGUAGE tag is used to specify the language in which all 
# documentation generated by doxygen is written.

OUTPUT_LANGUAGE        = English

# The INPUT tag can be used to specify the files and/or directories that contain 
# documented source files. You may enter file names like "myfile.cpp"
# or directories like "/usr/src/myproject". 
# Separate the files or directories with spaces.

INPUT                  =
			 
# If the value of the INPUT tag contains directories, you can use the 
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
# and *.h) to filter out the source-files in the directories. If left 
# blank the following patterns are tested: 
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp 
# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm

FILE_PATTERNS          = *.h *.hh *.idl

# The RECURSIVE tag can be used to turn specify whether or not subdirectories 
# should be searched for input files as well. Possible values are YES and NO. 
# If left blank NO is used.

RECURSIVE              = YES

# If the GENERATE_HTML tag is set to YES (the default) Doxygen will 
# generate HTML output.

GENERATE_HTML          = YES

# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank -html- will be used as the default path.

HTML_OUTPUT            = html

# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will 
# generate Latex output.

GENERATE_LATEX         = NO

# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank -latex- will be used as the default path.

LATEX_OUTPUT           = latex

Come si vede, attraverso il file di configurazione, l'utente stabilisce:

• Il nome del progetto
• la directory dove verrà generato il materiale (directory di destinazione)
• la lingua della documentazione prodotta
• la directory dove si trovano i file sorgente da documentare (directory di origine)
• l'estensione dei file di input da considerare come origine
• l'indicazione di ricorsività nella directory di origine
• l'indicazione di generazione del formato HTML
• nome della directory di destinazione per il formato HTML
• l'indicazione di generazione del formato LaTeX
• nome della directory di destinazione per il formato LaTeX

Doxygen è in grado di generare un file di configurazione generico con il comando

doxygen -g <config-file>

il file generato automaticamente da doxygen contiene dei parametri generici che l'utente può personalizzare o lasciare invariati.

Utilizzo

Dopo aver installato Doxygen ed aver generato ed eventualmente modificato il file di configurazione, si può invocare l'esecuzione di Doxygen con il comando

doxygen <config-file>

al termine della elaborazione, il materiale prodotto sarà disponibile nella directory di destinazione indicata nel file di configurazione.

Altri progetti

Altri progetti

• Wikimedia Commons

• Wikimedia Commons contiene immagini o altri file su Doxygen

Collegamenti esterni

• (EN) Sito ufficiale, su doxygen.org.
• (EN) Doxygen, su SourceForge.
• Doxygen, su packages.debian.org.
• (EN) Doxygen, su GitHub.
• Repository sorgenti di Doxygen, su github.com.
• (EN) Doxygen, su Free Software Directory.
• (EN) 10 Minuti per documentare il codice, su codeproject.com.