Documentazione C/C++ Sotto Linux: Una Guida Pratica a Doxygen

Scrivere codice è solo metà del lavoro. Se non sai cosa fa una funzione tra sei mesi, il codice non vale molto. In ambienti Linux, dove la filosofia man è sacra, Doxygen è lo strumento principe per generare documentazione professionale partendo da commenti strutturati nel codice.

Questo articolo ti guiderà dalla configurazione di base fino alla pubblicazione di una documentazione elegante, con esempi pratici e comandi shell.

Su qualsiasi distribuzione moderna, l’installazione è immediata:

# Debian / Ubuntu / Mint
sudo apt install doxygen graphviz

# Fedora / RHEL
sudo dnf install doxygen graphviz

# Arch / Manjaro
sudo pacman -S doxygen graphviz

Pro-tip: Graphviz non è obbligatorio, ma è fortemente consigliato per generare i diagrammi delle relazioni tra classi (inheritance, call graph).

Primi Passi: Un Progetto Esempio

Creiamo una struttura minimale:

project/
├── src/
│   ├── main.c
│   └── utils.h
└── Doxyfile

File src/utils.h:
Scriviamo commenti nel formato Doxygen:

/**
 * @brief Calcola il fattoriale di un numero.
 *
 * Funzione ricorsiva che restituisce il fattoriale.
 * @param n Numero intero non negativo.
 * @return Il fattoriale di n, oppure 1 per n=0.
 */
int fattoriale(int n);

File Doxyfile:
Genera il file di configurazione con:

doxygen -g Doxyfile

Ora apri il file e modifica solo queste righe (le altre puoi lasciarle con i valori predefiniti):

PROJECT_NAME           = "Il Mio Progetto C"
INPUT                  = src/
RECURSIVE              = YES
GENERATE_LATEX         = NO   # Se non ti serve PDF via LaTeX
HAVE_DOT               = YES  # Abilita i grafi (richiede graphviz)

Generazione della Documentazione

Basta un comando:

doxygen Doxyfile

Verrà creata una cartella html/. Apri html/index.html con il browser e ammira il risultato.

Per generare il manuale in formato man (integrato nel sistema):

doxygen Doxyfile  # Se già eseguito, ok
# La sezione man è generata automaticamente se MAN_OUTPUT è abilitato

Funzionalità Avanzate (e Utili)

Tag più comuni

Gruppi e Moduli

Raggruppa funzioni correlate:

/** @defgroup matematica Funzioni matematiche
 *  Gruppo per le operazioni di base.
 *  @{
 */

int somma(int a, int b);
int prodotto(int a, int b);

/** @} */

Esempio completo: programma C con Doxygen

Ecco un mini programma che documenta sé stesso:

/**
 * @file main.c
 * @brief Programma dimostrativo per articolo Doxygen.
 * @author Mario Rossi
 */

#include <stdio.h>

/**
 * @brief Funzione principale.
 * @return 0 se eseguito con successo.
 */
int main(void) {
    printf("Ciao, Doxygen!\n");
    return 0;
}

Integrazione con make

Per automatizzare la generazione, aggiungi un target nel Makefile:

doc:
	doxygen Doxyfile
	@echo "Documentazione generata in html/"

Ora basta scrivere make doc.

Output PDF (se ti serve)

Se preferisci un PDF anziché solo HTML, riattiva LaTeX nel Doxyfile:

GENERATE_LATEX = YES

Poi, dentro la cartella latex/:

cd latex/
make

Riceverai un file refman.pdf.

Consigli per un Codice Ben Documentato

1. Documenta sempre l’interfaccia pubblica (funzioni esportate, struct, enums).
2. Non esagerare con i commenti ovvi (es. "int a è un intero").
3. Usa i riferimenti (@see o @ref) per collegare concetti correlati.
4. Aggiorna i commenti quando modifichi il codice: la documentazione “buggata” è peggio di nessuna documentazione.

Doxygen trasforma il tuo codice in una risorsa consultabile con pochi comandi. In Linux, dove la riga di comando regna, padroneggiare Doxygen significa trasformare il tuo progetto da “cassetto dei misteri” a software professionale documentato.

Allegato: Comandi Rapidi