Nouvelle version pour Doxygen

Posté par (page perso) . Modéré par patrick_g. Licence CC by-sa
36
6
sept.
2011
Doc

Doxygen est un générateur de documentation à partir du code source de différents langages. Il est disponible pour les langages suivants : C, C++, C#, Fortran, Java, Objective-C, PHP, Python, IDL, VHDL, TCL et D. Les formats de sorties sont : HTML, LaTeX, RTF, PostScript, PDF (avec les hyperliens), HTML compressé et les pages de manuel Unix.

La liste des utilisateurs est grande, on retrouve KDE, Drupal, DotClear, LLVM, OpenTTD…

Doxygen est compatible avec les conventions de JavaDoc et celles de Qt. Il permet aussi de générer des graphes d’utilisation et d’héritage. Il s’utilise de la manière suivante (exemple en C++) :

/*! Classe d'exemple 
 * @author Xavier Claude
*/
public class Exemple {
    
    protected:
        /*! la description d'un attribut */
        std::string s;
    public:
        /*! La description d'une classe
         * @param newS la nouvelle valeur de s
         * @return true en cas de succès
         */
         bool setS(std::string newS);
}

Comme cela fait longtemps que les nouvelles versions de Doxygen n’ont pas été évoquées sur LinuxFr.org, un résumé des nouveautés des dernières versions est disponible en deuxième partie. Il y a bien sûr eu, en plus, beaucoup de corrections de bogues et quelques changements de comportement.

1.6.0

Date de sortie : 20 août 2009.

  • La documentation des descriptions des interfaces XML de DBus est prise en charge.
  • Une option permet de placer les constructeurs et les destructeurs avant les autres méthodes.

1.6.1

Date de sortie : 25 août 2009.

Pas de nouveautés, uniquement des corrections de bogues.

1.6.2

Date de sortie : 30 décembre 2009.

  • La recherche en utilisant PHP (pour la sortie HTML) est de nouveau disponible. Cette méthode permet de meilleures recherches et une meilleure extensibilité que la méthode utilisant JavaScript.
  • Il est possible de générer des fichiers d’index compatibles avec Eclipse, afin de permettre l’affichage de la documentation dans ce dernier.
  • Le rendu des formules sur des fonds non blancs a été amélioré grâce à une meilleure méthode d’anticrénelage.
  • La compilation est possible sur Mac OS X 10.6.

1.6.3

Date de sortie : 21 février 2010.

  • L’utilisation de la commande « \dir » sans argument va créer un répertoire de documentation pour le répertoire dans lequel la commande a été trouvée.

1.7.0

Date de sortie : 15 juin 2010.

  • Les couleurs de la sortie HTML peuvent être facilement changées.
  • Le programme dot (utilisé pour la génération de graphe) est utilisé via plusieurs instances en parallèle, pour tirer partie des architectures multi‐cœurs.
  • Il est possible de déterminer si les liens vers les symboles doivent s’ouvrir dans une nouvelle fenêtre.

1.7.1

Date de sortie : 25 juin 2010.

  • Il est possible de choisir si les formules doivent être transparentes ou non pour la sortie HTML.

1.7.2

Date de sortie : 9 octobre 2010.

  • Les extensions de blocs d’objets d’Apple pour le C, le C++ et l’Objective-C sont prises en charge.
  • Les constructeurs et destructeurs Python sont désormais détectés.
  • Il est possible de spécifier explicitement la fin d’une section « \internal » avec « \endinternal ».
  • Le style d’espace de nommage pour PHP 5.3 et supérieur est pris en charge.
  • Il est possible de spécifier le type des paramètres en PHP en utilisant la syntaxe « @param type $paramname docs ».
  • Le rendu des formules peut‐être réalisé en JavaScript, via MathJax, pour la sortie HTML.

1.7.3

Date de sortie : 3 janvier 2011.

  • Il est possible de spécifier le format SVG pour les images générées par dot.
  • L’assistant permet de sélectionner un synopsis et un logo pour le projet.

1.7.4

Date de sortie : 28 mars 2011.

  • Une option permet d’afficher les classes groupées dans la documentation de groupe et non pas sur une page séparée.
  • Il est désormais possible d’ajouter facilement des pages HTML à l’index lors de la génération de celui‐ci.
  • Le bas de page de la sortie LaTeX est configurable.

1.7.5

Date de sortie : 14 août 2011.

  • Génération de SVG interactifs (zoom et panorama).
  • Ajout du langage TCL.
  • La commande « @copyright » a été ajoutée.
  • Prise en charge des extensions MathJax.
  • La commande « \cite » de LaTeX peut être utilisée pour citer des références (même sur d’autres sorties que LaTeX).
  • Ajout de la commande « \snippet » qui permet d’ajouter une partie d’un fichier source. La partie doit être délimitée dans le fichier.
  • # Petites questions tant qu'on y est...

    Posté par (page perso) . Évalué à 3.

    Je connais bien doxygen, ce projet m'a sauvé la vie pour abordé des énormes projet non documenté.

    J'ai une question, est-ce qu'il est possible d'obtenir un rapport des statistiques du code analysé par exemple : nombre de classe, de méthode, nombre de ligne moyenne par méthode, nombre de ligne moyenne par classe ?

    En gros, doxygen serait-il en fait l'outils de loc que je recherche depuis toujours pour le C++ :)

    • [^] # Re: Petites questions tant qu'on y est...

      Posté par . Évalué à 2.

      Sonar me parait plus indiqué pour ça.

      Le hic, c'est que je ne sais pas s'il supporte bien le C++ :(

      • [^] # Re: Petites questions tant qu'on y est...

        Posté par (page perso) . Évalué à 1.

        J'ai posé cette question car, j'ai testé sonar et ça ne marche pas très bien avec le c++. Alors que doxygen, possède largement les capacités pour mettre en place un tel système.... un jour si j'ai le temps, je verrais si je ne peux pas y apporter mon grain de sel dans ce sens.

  • # Bon programme

    Posté par . Évalué à 2.

    Ravi de voir que le projet avance toujours.

    Je m'en étais beaucoup servi pour mon premier boulot. On peut faire des choses vraiment sympa assez rapidement. De plus, la syntaxe est assez légère.

    Dommage qu'il n'y ait pas encore de support pour le langage Lua.

  • # Bof pour du python

    Posté par (page perso) . Évalué à 3.

    Toutes les fois que j'ai voulu utiliser Doxygen pour du python, ça été une catastrophe. D'abord il était pas compatible avec la documentation normale d'une fonction python. Puis quand ça a été ajouté, il y avait plein de cas où mes fonctions ou classes documentées n'apparaissaient pas dans la doc finale.

    • [^] # Re: Bof pour du python

      Posté par . Évalué à 6.

      Pour python il vaut mieux utiliser Sphinx. C'est fait pour.

      • [^] # Re: Bof pour du python

        Posté par . Évalué à 4.

        Il existe également Epydoc, qui fonctionne un peu à la manière de Doxygen et qui permet deux analyses : analyse lexicale classique et introspection par chargement des modules dans un interpréteur Python. En gros, il devrait tout trouver.

        Le projet n'est plus très actif, mais Epydoc fonctionne sans aucun problème.

  • # Anecdote

    Posté par . Évalué à 10.

    Le jour où j'ai découvert Doxygen, c'est en lisant une documentation générée avec.

    Je trouvais la documentation rédigée de façon très sèche, très peu cordiale, sans touche d'humour, avec des exemples d'usage de fonctions répétitifs voire redondants (Quand on a compris la fonction FooDirect, FooReverse, BarDirect, est-ce nécessaire de documenter BarReverse avec exactement les mêmes noms de variable pour expliquer qu'elle effectue Bar de façon inversée?). Et certains points compliqués n'étaient vraiment pas détaillés, alors qu'il y avait au contraire trop de détails sur des fonctions triviales.

    Du coup j'ai voulu en toucher un mot à l'auteur. Ça tombait bien, le PDF était signé, c'était marqué "Generated by Doxygen". Mais qui est Doxygen? Ah, d'accord. Salut Doxygen. :)

    THIS IS JUST A PLACEHOLDER. YOU SHOULD NEVER SEE THIS STRING.

    • [^] # Re: Anecdote

      Posté par . Évalué à 10.

      Doxygen construit une référence qui est assez indigeste, mais il est possible d'obtenir quelque chose de plus facile à lire (et plus utile). Je prends pour exemple la documentation d'ALSA (qu'est-ce que je fais !) qui présente les concepts de l'API, permet de naviguer vers la référence des fonctions et de voir des exemples. Doxygen donne donc les moyens de réaliser une documentation propre et agréable ; ensuite c'est aux développeurs d'écrire un peu en langage naturel pour obtenir une documentation utile.

  • # \cite

    Posté par . Évalué à 1.

    Petit rectificatif: le \cite (dont je rêve depuis longtemps) n'est pas encore très fonctionnel : le ticket bugzilla a été réouvert après la release 1.7.5 (cf https://bugzilla.gnome.org/show_bug.cgi?id=503239).

    Si vous avez réussi à le faire marcher, je suis preneur..

Suivre le flux des commentaires

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