Doxygen

Informations
Développé par	Dimitri van Heesch et contributeurs
Première version	26 octobre 1997
Dernière version	1.13.2 (9 janvier 2025)
Dépôt	github.com/doxygen/doxygen
Assurance qualité	Intégration continue
Écrit en	C++
Interface	Qt
Système d'exploitation	Systèmes d'exploitation Mac OS, Microsoft Windows et type Unix
Langues	anglais
Type	Générateur de documentation
Politique de distribution	gratuiciel
Licence	Licence publique générale GNU version 2
Site web	www.doxygen.org

Doxygen est un générateur de documentation sous licence libre capable de produire une documentation logicielle à partir du code source d'un programme. Pour cela, il tient compte de la syntaxe du langage dans lequel est écrit le code source, ainsi que des commentaires s'ils sont écrits dans un format particulier.

Le code de Doxygen a été écrit en grande partie par Dimitri van Heesch.

Présentation

Doxygen est la contraction de « dox » (« docs », abréviation anglaise de « documents ») et de « gen » (« generator »), « générateur de documentation ».

Doxygen peut analyser des fichiers sources écrits dans les langages C, Objective C, C#, PHP, C++, Java, Python, IDL, Fortran, VHDL, Tcl et dans une certaine mesure D.

La documentation peut être produite dans les formats suivants : HTML (compressé ou non), LaTeX, RTF, PostScript, PDF avec hyperliens, et prochainement XML (en cours de développement).

Intérêt

En intégrant la documentation au code source, Doxygen favorise la cohérence entre documentation et code. Il incite aussi les développeurs à documenter leur code.

Il est également possible d'extraire de la documentation à partir d’un code source non documenté au préalable, ce qui peut faciliter la compréhension d'un programme dont le code est compliqué.

De nombreux projets, tels que KDE, utilisent Doxygen pour générer la documentation de leur API. KDevelop intègre le support de Doxygen. De nombreux éditeurs de texte proposent des modes ou des scripts pour faciliter l'écriture des commentaires Doxygen et la génération de la documentation.

Les informations suivantes peuvent être extraites des sources :

prototype et documentation des fonctions, qu'elles soient locales, privées ou publiques, etc. ;
liste des fichiers inclus ;
liste des modules (groupements définis dans la documentation) ;
documentation des structures de données ;
prototype et documentation des classes et leur hiérarchie ;
différents types de graphes : diagrammes de classe, de collaboration, d'appels, d'inclusion, etc. (pour générer certains de ces diagrammes, l'outil gratuit Dot est nécessaire) ;
un index de tous les identifiants ;
des fichiers sources annotés (par exemple avec les numéros de lignes) et navigables (par exemple avec HTML, avec lequel des identifiants renvoient vers la documentation associée).

Exemple

Le code ci-dessous illustre la manière dont Doxygen permet de documenter le code.

/**
* La classe Time représente un instant.
* @author Paul Hochon
*/
class Time {

    /**
    * Constructeur.
    * Fixe l'instant à une valeur précise.
    * @param timemillis Millisecondes écoulées depuis le 1er janvier 1970
    */
    Time(int timemillis) {
        ...
    }

    /**
    * Récupère l'instant actuel.
    * @return Un instant correspondant à l'instant présent
    */
    static Time now() {
        ...
    }
}

Les commentaires du langage cible (ici Java) sont spécialisés pour indiquer à Doxygen qu'il doit les prendre en compte. Ainsi, les commentaires commencent avec /** plutôt que /*. Des balises spécifiques à l'intérieur de ces commentaires sont également interprétées par Doxygen (par exemple : @param).

Dans cet exemple, la rédaction des commentaires utilise le format Javadoc, avec lequel Doxygen est compatible. Doxygen propose son propre format, qui est fonctionnellement équivalent.

Les tags les plus utilisés (par ordre alphabétique)^[2]

@author pour donner le nom de l'auteur.
@brief pour donner une description courte.
@class pour documenter une classe.
@def pour documenter un #define.
@deprecated pour spécifier qu'une fonction/méthode/variable… n'est plus utilisée.
@details pour donner une description longue.
@enum pour documenter un type énuméré.
@exception pour documenter une exception.
@file pour documenter un fichier.
@fixme pour indiquer un code défectueux, « à réparer ».
@fn pour documenter une fonction.
@interface pour documenter une interface IDL.
@li pour faire une puce.
@namespace pour documenter un namespace.
@package pour documenter un package Java.
@param pour documenter un paramètre de fonction/méthode.
@return pour documenter les valeurs de retour d'une méthode/fonction.
@see pour renvoyer le lecteur vers quelque chose (une fonction, une classe, un fichier…).
@since pour faire une note de version (ex : disponible depuis…).
@struct pour documenter une structure C.
@throws pour documenter les exceptions possiblement levées.
@todo pour indiquer une opération restant « à faire ».
@typedef pour documenter la définition d'un type.
@union pour documenter une union C.
@var pour documenter une variable / un typedef / un énuméré.
@version pour donner le numéro de version.
@warning pour attirer l'attention.

Plate-forme

Doxygen est écrit sous Linux et Mac OS, avec un souci affiché de portabilité. Il fonctionne sur la plupart des systèmes Unix et il est disponible en version exécutable sur Microsoft Windows.

DoxyWizard

DoxyWizard est une interface graphique permettant de configurer les options de génération de Doxygen et de lancer l'extraction de la documentation. Comme Doxygen, il est disponible sur différentes plates-formes.

Licence

Doxygen est publié sous licence GPL.

Notes et références

↑ « Doxygen release 1.13.2 », 9 janvier 2025 (consulté le 9 janvier 2025)
↑ « Doxygen: Overview », sur www.doxygen.nl (consulté le 2 février 2025)

Voir aussi

Javadoc, outil de génération de documentation pour le langage Java, développé par Sun
OCamlDoc, outil de génération de documentation pour le langage OCaml, développé par l'INRIA;
PhpDocumentor, outil de génération de documentation pour le langage PHP
SandCastle, outil de génération de documentation pour les langages .Net, édité par Microsoft
Sphinx, outil de génération de documentation pour le langage Python, développé par la Python Software Foundation;
Visdoc, outil de génération de documentation HTML pour le langage ActionScript 2 (AS2) & 3 (AS3) et Java (MAC uniquement)
XMLDoc, outil open source de génération de documentation pour les langages .Net (en cours de développement)

Lien externe

(en) Site officiel

Portail des logiciels libres

[wikidata-bb6426c6a86395621d7ddf96c49c13bad2f343c2-1] « Doxygen release 1.13.2 », 9 janvier 2025 (consulté le 9 janvier 2025)

[2] « Doxygen: Overview », sur www.doxygen.nl (consulté le 2 février 2025)

[1]

[2]