Présentation

Doxygen est un programme formidable. Il permet en effet de générer de la documentation directement depuis vos sources ! L'écriture de documentation étant presque toujours la bête noire des programmeurs, qui préfèrent coder qu'expliquer ce qu'il font, cet outils est très utile. Il est capable de générer à partir d'un ensemble de fichiers-sources (en C, C++, Java, Objective-C, Python, éventuellement PHP, C#, et même D) de générer de la documentation pour chaque classe, fonction, avec les relations d'héritage, etc.

De plus, ce programme est sous license GNU GPL et est conçu sous Linux et Mac OS X, mais tourne très bien sous la plupart des UNIX et sous Windows ! Dépéchez-vous donc de le télécharger sur son site officiel (vous pouvez aussi le télécharger via votre gestionnaire de paquet, le nom du paquet étant “doxygen”

Doxygen permet de générer de la documentation à partir d'un code source “brut”, mais cela n'a que peut d'intérêt. Le principe de Doxygen est d'utiliser des commentaires spéciaux pour introduire de courtes description pour chaque classe, méthode, champ, etc…

Voici un exemple de classe bien documentée :

/**
 * @file character.h Ce fichier contient la définition de la classe Character.
 */
 
/**
 * Un personnage.
 *
 * Cette classe représente un personnage du jeu. C'est la classe de base dont* héritent tous les monstres.
 */
class Character 
{
protected:
    Vector2D m_vPosition; /**< La position du personnage. */
    double m_dLife; /**< Les points de vie (HPs) du personnage. */
public:
    /**
     * Déplacement.
     *
     * Cette méthode déplace le personnage. Elle est appelée à chaque boucle.
     * @param dTimeElapsed Le temps écoulé depuis la dernière boucle, pour les
     * calculs physiques.
     * @return false si le personnage est mort (et doit être retiré du jeu),
     * true sinon.
     */
    virtual bool Move(double dTimeElapsed);
};

Comme vous pouvez le voir, c'est assez simple. Vous devez simplement utiliser /** ou /*! pour ouvrir les commentaires et /// ou //! pour ceux placés sur une seule ligne pour introduire une description (elle doit être placée avant l'élément commenté, ou vous devrez rajouter le caratère <, par exemple : //!< description). Ici, il y a d'abord une description courte (par exemple “Un personnage.”) et ensuite une description plus complète (“Cette classe représente…”). Notez aussi qu'il y a certains paramètres spéciaux, précédés d'un ‘@’; voici les principales directives reconnues :

• @file fichier description : Fourni une description à un fichier.
• @param paramètre description : Décrit le paramètre d'une fonction.
• @return description : Décrit la valeur de retour d'une fonction.