Créer une documentation à partir des commentaires

doxygen est un outil pour générer de la documentation à partir de sources C, C++, Python etc. correctement commentés.

Installation de doxygen

L'outil est disponible dans les paquets Linux traditionnels :

    sudo dnf install doxygen

Bien commenter

Au début de chaque fichier, il faut quelque chose comme :

        /**
        * \file main.c
        * \brief Programme de tests.
        * \author Franck.H
        * \version 0.1
        * \date 11 septembre 2007
        *
        * Programme de test pour l'objet de gestion des chaines de caractères Str_t.
        *
        */

Pour les fonctions, on commente comme ça :

        /**
        * \fn static Str_t * str_new (const char * sz)
        * \brief Fonction de création d'une nouvelle instance d'un objet Str_t.
        *
        * \param sz Chaine à stocker dans l'objet Str_t, ne peut être NULL.
        * \return Instance nouvellement allouée d'un objet de type Str_t ou NULL.
        */

Utilisation de doxygen

Dans le répertoire d'un projet, on lance doxygen -g pour créer un fichier doxyfile qui est le fichier de configuration de la documentation.

On lance alors doxygen pour générer la documentation.