Doxygen en 1.5.0

Posté par  . Modéré par Jaimé Ragnagna.
Étiquettes :
0
18
oct.
2006
Doc
Le générateur de documentation de code source doxygen est sorti en version 1.5.0 le 17 octobre dernier.

C'est une bonne occasion de présenter très brièvement ce qui devrait faire partie de toute boîte à outils d'un bon programmeur.

Doxygen est donc un logiciel permettant de documenter facilement son code par un système de commentaire-tags. Les utilisateurs de javadoc, par exemple, se retrouveront facilement dans la manière de procéder, cependant on dénombre près de 170 tags par défaut pour doxygen auquel s'ajoute un système permettant d'ajouter ses propres tags afin de répondre aux besoins du projet.

En plus de la documentation des sources (prototype des fonctions, des classes), on peut obtenir les informations suivantes :
  • Liste des fichiers inclus;
  • Documentation des structures de données;
  • Hiérarchie des classes;
  • Différents types de graphiques : diagrammes de classe, de collaboration, d'appels, d'inclusion, etc;
  • Un index de tous les identifiants;
  • Des fichiers sources annotés.


La documentation produite est généralement au format HTML à cause de sa facilité d'emploi, cependant il est possible d'obtenir des fichiers LATEX, PostScript, PDF, XML, man et même Word et CHM.

Doxygen a été écrit en grande partie par Dimitri van Heesch qui trouvait, à l'époque, la documentation générée pour Qt très jolie et doc++ trop limité pour réaliser un travail similaire.

Aujourd'hui doxygen supporte C/C++, Java, (Corba et Microsoft) Java, Python, IDL, C#, Objective-C et en partie D et PHP.

Doxygen est distribué sous licence GPL, un binaire est disponible pour Windows 95 à XP et pour Mac OS X mais toute bonne distribution doit le mettre à disposition (nécessite la libqt). La version 1.5.0 apporte surtout beaucoup de correctifs et assez peu de nouvelles fonctionnalités (voir le changelog complet pour d'avantage d'informations).

On notera toutefois (traduction libre) :
  • Ajout d'exemples pour montrer comment configurer et faire tourner doxygen pour une application et utiliser les informations collectées sans générer la sortie;
  • id 322467: Les sections produites par \note, \warning, \remarks etc, ont maintenant un label de classe dans le HTML généré (tag ) aussi vous pouvez leur donner un style distinct en utilisant des feuilles de styles (HTML_STYLESHEET);
  • Ajout de fichiers de projet pour construire doxygen sous Visual Studio 2005;
  • Mises à jour des traductions pour le Tchèque, le Danois, l'Allemand et le Catalan;
  • Ajouts de traductions pour l'Arabe (merci à Moaz Reyad);
  • Ajouts de traductions pour le Perse (merci à Ali Nadalizadeh).

Aller plus loin

  • # UTF-8 ?

    Posté par  (site web personnel) . Évalué à 6.

    Cette année j'ai eu à utiliser Doxygen ... et le problèyme c'est que mes fichiers sources sont codés UTF-8, du coup doxygen avait un peu de mal, pensant qu'il s'agissait d'iso-8859-1[5].

    Alors, c'est possible de configurer doxygen pour qu'il gère l'utf-8 ? D'après ce que j'avais vu sur google, cela ne semblait pas être le cas.
    • [^] # Re: UTF-8 ?

      Posté par  (site web personnel) . Évalué à 2.

      Je rencontre le même problème. En utilisant les entités HTML, ça passe comme il faut, même pour le pdf.
      • [^] # Re: UTF-8 ?

        Posté par  . Évalué à 1.

        C'est quoi les entités HTML ?
        • [^] # Re: UTF-8 ?

          Posté par  . Évalué à 2.

          Des exemples plutôt qu'un long discours :

          É -> É
          é -> é
          è -> è
          ë -> ë
          ä -> ä
          © -> ©
      • [^] # Re: UTF-8 ?

        Posté par  (site web personnel) . Évalué à 2.

        Enfin, jai une touche é sur mon clavier, ce n'est pas pour rien, enfin j'espère :'-(
        • [^] # Re: UTF-8 ?

          Posté par  (site web personnel) . Évalué à 1.

          Euh, je suppose que tu veux utiliser « é » pour des mots comme « café » ou « fiancey », mais ne me dis pas que tu commentes ton code en Français quand même ?

          ;-)
          • [^] # Re: UTF-8 ?

            Posté par  . Évalué à 4.

            En quoi cela pose problème de commenter en français? :o
            • [^] # Re: UTF-8 ?

              Posté par  . Évalué à 5.

              Par souci d'intéropérabilité avec les développeurs du monde entier, il vaut mieux utiliser le volapuk ou le latin.
              • [^] # Re: UTF-8 ?

                Posté par  . Évalué à 4.

                Moi, je code exclusivement mes projets open source en esperanto pour que tout le monde puisse contribuer...
              • [^] # Re: UTF-8 ?

                Posté par  . Évalué à 3.

                J'ai travaillé sur des projets où l'utilisation du français était obligatoire pour toute la documentation, commentaires du code inclus.
                Ça serait donc effectivement sympa que l'utf8 soit supporté.
            • [^] # Re: UTF-8 ?

              Posté par  (site web personnel) . Évalué à 2.

              En l'occurence, je commente en anglais, sauf dans les projets de l'IUT :)
            • [^] # Re: UTF-8 ?

              Posté par  (site web personnel) . Évalué à 2.

              Si je te dis que j'ai trouvé des commentaires en Allemand dans le code source d'OpenOffice, tu comprends de quoi je parle ? (lesdits commentaires datant vraissemblablement de StarOffice, propriétaire et développé par une boite allemande)

              Enfin, j'ai un copain qui bossait sur du code commenté en polonais, mais il a appris plus tard que les commentaires importants étaient ceux en anglais. Le polonais, c'était juste pour les trucs genre « penser à acheter des poireaux en rentrant ce soir » ;-).
  • # Question à deux balles

    Posté par  (site web personnel) . Évalué à 7.

    Comment prononcez-vous Doxygen? Les gens autour de moi disent "d - oxygen", et moi en un seul mot (ben oui, ça commence comme "doc-umentation").
    Aidez-moi, dites moi que je ne suis pas fou!
  • # Mieux que javadoc ?

    Posté par  (site web personnel) . Évalué à 4.

    Salut,

    Non ce n'est pas un troll, mais une question sérieuse :-)
    Étant données les fonctionnalités listées, je me dis de plus en plus que doxygen vaut le coup par rapport à javadoc. Qu'en est-il en pratique ?
    Des gens qui code en java utilisent-ils doxygen ? En êtes vous contents ?

    Existe-t-il des générateurs de commentaires pour doxygen ? Comme dans eclipse, où on peut générer des gabarits de commentaires. Où encore umbrello qui génère du code java avec les commentaires tapés dans les modèles.

    Bon après, c'est sûr que je pourrai essayer par moi même pour me faire une idée ;-)

    Merci
    • [^] # Re: Mieux que javadoc ?

      Posté par  . Évalué à 3.

      Pour emacs tu as doxymacs (http://doxymacs.sourceforge.net/), par contre pour Eclipse je trouvais que le plugin doxygen, la dernière fois que je l'avais testé, un peu léger..
    • [^] # Re: Mieux que javadoc ?

      Posté par  . Évalué à 1.

      Petite remarque : Doxygen supporte plusieurs "formats" pour les commentaires donc les "/** */" qu'utilise Javadoc. Il y a par ailleurs un certain de balises courantes qui sont identiques. Ca peut te motiver pour essayer, ce ne sera pas très difficile.

      Pour répondre à ta question, j'ai utilisé Javadoc quand j'ai codé en Java, et Doxygen dans les autres cas, avec le format de commentaires décrit plus haut.

      --
      http://www.tessier-net.org
  • # DoxyS

    Posté par  . Évalué à 4.

    A noter aussi un autre outils qui est parti d'un fork de Doxygen : DoxyS
    http://www.doxys.dk/

    Le rendu HTML est vraiment différent :
    http://www.doxys.dk/doxys_homepage/Screenshots0_page_descrip(...)

    Et surtout on à une fonction de recherche (incrémentale d'ailleurs, c'est pas mal !) qui ne nécessite pas de serveur Apache (pour le php), contrairement à Doxygen.

    Par contre, ça évoluent beaucoup moins vite que Doxygen, selon les tags utilisés dans Doxygen il n'y a pas d'équivelent avec DoxyS, et de mémoire, ça ne gère "que" le C, C++...

    Nous on a testé les 2, et finalement, on utilise les 2... Les fichiers de config pour générer les 2 docs sont relativement similaires.
  • # Doxygen en python

    Posté par  (site web personnel) . Évalué à 2.

    Quelqu'un l'a deja utilise en python ? La derniere fois que j'ai essaye, c'etait bugge a mort. Impossible d'avoir du cross referencement correct des noms de fonctions dans les autres documentations. Les variables globales etaient ignorees. Soi-disant, ca supporte la documentation format python mais en fait, ca ne marchait pas du tout. Etc etc.

    J'ai pas l'impression que la generation python soit testee correctement.
    • [^] # Re: Doxygen en python

      Posté par  . Évalué à 2.

      Je suis en ce moment sur un projet en Python. J'ai donc jeté un oeil (assez rapide) sur les systèmes de génération de documentation. J'en arrive au même constat que toi : le résultat de doxygen n'est pas satisfaisant à mes yeux (trop brouillon), donc pour l'instant je reste avec pydoc.
      • [^] # Re: Doxygen en python

        Posté par  (site web personnel) . Évalué à 1.

        J'ai galere aussi avec pydoc et avec les autres generateurs de documentation sous python. Globalement, je reste tres decu de l'etat de tout ca.

        DOxygen est quand meme celui qui a le plus de potentiel, etant donne la qualite de la documentation qu'il genere (en C++ et en java). Vivement que quelqu'un reporte le flambeau du parser python.
  • # Use sysprof Luke...

    Posté par  . Évalué à 7.

    Petite info, au cas où d'autres se seraient retrouvés confrontés au même soucis, parceque je ne l'ai pas vu documenté sur le web...

    Il y a qlqs temps, j'avais été surpris de la lenteur pour compiler la doc d'un projet C++ de taille moyenne auquel je jetais un oeil. Ça prennais ~30 minutes. En fait, un petit coup de sysprof¹ m'a montré que :
    - ~85% de ce temps était passé dans le code de génération des graphiques, c'est à dire pas dans Doxygen lui même, mais dans Graphiz (le machin qui fourni entre autres la commande "dot") ;
    - sur ce temps là, ~90% était passé dans des fonctions d'initialisation de Fontconfig.

    La bonne nouvelle, c'est qu'un update de Fontconfig de la 2.3.2 à la récente 2.4.1 a réduit ce temps pour le rendre ~négligeable. Et la même tâche Doxygen me prends maintenant moins de 5 minutes. Voilà, c'est tout, elle est pas belle la vie ?

    Bon, évidemment, si votre distrib package Graphiz pour qu'il n'utilise pas Fontconfig, ce qui est aussi possible mais donne des polices souvent moins jolies, vous n'aurez pas rencontré ce problème.

    ¹ http://www.daimi.au.dk/~sandmann/sysprof/

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.