1. #1
    Membre du Club
    Profil pro
    Inscrit en
    mai 2007
    Messages
    69
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : mai 2007
    Messages : 69
    Points : 64
    Points
    64

    Par défaut Commentaires doxygen dans les headers ou dans les sources

    Bonjour,

    Je pense que mon titre est suffisamment explicite. Je voulais savoir ce qui était le mieux et le plus pratique ... Introduire la doc dans les .h ou plutôt dans les .cpp ?

    Merci !

  2. #2
    Expert éminent sénior
    Avatar de Médinoc
    Homme Profil pro
    Développeur informatique
    Inscrit en
    septembre 2005
    Messages
    26 384
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 33
    Localisation : France

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : septembre 2005
    Messages : 26 384
    Points : 37 867
    Points
    37 867

    Par défaut

    Sans réfléchir, je dirais les headers: Si tu fais une bibliothèque propriétaire, tu distribues quand même les headers avec, ce qui permet d'avoir les commentaires sous la main même quand tu n'as pas la doc...

    D'un autre côté, ça peut peut-être gêner les commentaires doxygen du client, auquel cas il vaudrait mieux qu'il soient dans les sources...
    SVP, pas de questions techniques par MP. Surtout si je ne vous ai jamais parlé avant.

    "Aw, come on, who would be so stupid as to insert a cast to make an error go away without actually fixing the error?"
    Apparently everyone.
    -- Raymond Chen.
    Traduction obligatoire: "Oh, voyons, qui serait assez stupide pour mettre un cast pour faire disparaitre un message d'erreur sans vraiment corriger l'erreur?" - Apparemment, tout le monde. -- Raymond Chen.

  3. #3
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    Salut,

    Il reste une troisième solution, étant donné que les commentaires doxygen ne sont - normalement - prévu que pour permettre d'indiquer la manière dont doivent être utilisées les classes / fonction / méthodes et que, partant, ils n'ont pas grand chose à voir avec les commentaires que je nommerais "d'implémentation" (qui permettent de se faire un rapide idée de l'algorithme suivi pour que la fonction arrive à son résultat).

    Cette troisième méthode est, tout simplement, de placer les commentaires doxygen dans... des fichiers tout à fait séparés... que tu peux choisir - ou non - de fournir avec les headers ou avec les sources
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  4. #4
    Expert confirmé
    Homme Profil pro
    Ingénieur développement logiciels
    Inscrit en
    décembre 2003
    Messages
    3 549
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Essonne (Île de France)

    Informations professionnelles :
    Activité : Ingénieur développement logiciels

    Informations forums :
    Inscription : décembre 2003
    Messages : 3 549
    Points : 4 625
    Points
    4 625

    Par défaut

    Avec doxygen il faut délimiter le début et la fin d'un fichier.
    Les commentaires d'un fichier entête ne sont donc pas considérés lorsqu'on génère la documentation associée à un fichier qui inclut cette entête.
    Boost ftw

  5. #5
    Membre éprouvé Avatar de Spout
    Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    904
    Détails du profil
    Informations personnelles :
    Âge : 32
    Localisation : France, Val d'Oise (Île de France)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux

    Informations forums :
    Inscription : février 2007
    Messages : 904
    Points : 975
    Points
    975

    Par défaut

    J'utilise beaucoup Doxygen dans mes codages et j'en place des commentaires... partout! Alors soit je ne l'utilise pas comme il faut, soit je ne comprends pas ce que vous dites quand vous parlez d'un choix entre les .h ou les .cpp , notamment:
    Avec doxygen il faut délimiter le début et la fin d'un fichier.
    Les commentaires d'un fichier entête ne sont donc pas considérés lorsqu'on génère la documentation associée à un fichier qui inclut cette entête.
    Exemple que de ce que je fais au quotidien:
    Code fichier.h : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    /**
    * \file Fichier.h
    * \brief Fichier de déclaration de la classe MyClass
    * \date 17/07/2008
    * \author Spoutspout
    */
    //------------------------------
    #ifndef MYCLASS_H
    #define MYCLASS_H
    //------------------------------
    /**
    * \class MyClass
    * \brief Classe MyClass qui sert à faire plein de trucs
    * \date 17/07/2008
    * \author Spoutspout
    */
    class MyClass {
    protected:
       int m_iAttribut;  //!< Un attribut de MyClass
    public:
       bool UneFonction(const int iParam);
    };
    //------------------------------
    #endif // MYCLASS_H
    Code fichier.cpp : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    /**
    * \file Fichier.cpp
    * \brief Fichier d'implémentation de la classe MyClass
    * \date 17/07/2008
    * \author Spoutspout
    */
    //------------------------------
    #include "Fichier.h"
    //------------------------------
    /**
    * \brief Fonction qui fait un truc
    * \param[in] iParam Un paramètre
    * \return True ou false, ça dépend
    */
    bool MyClass::UneFonction(const int iParam)
    {
    ....
    }
    //------------------------------
    Est-ce une mauvaise utilisation de Doxygen? Je précise que tous mes commentaires servent bien à quelque chose et son pris en compte dans la doc générée.
    "L'ordinateur obéit à vos ordres, pas à vos intentions." [Anonyme]

  6. #6
    Modérateur

    Homme Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    4 254
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : février 2007
    Messages : 4 254
    Points : 7 608
    Points
    7 608
    Billets dans le blog
    3

    Par défaut

    Non non... c'est très bien...
    Doxygen ne considère pas les commentaires dans les fichiers importés, mais nul besoin de délimiter le début et la fin de fichier...
    Par contre nul besoin de répéter la définition doxygen est assez grand pour ça

    Mon utilisation de doxygen est un poil différente...
    D'abord au niveau notation.... je préfère des commentaires genre:

    Dans le header:
    Code c++ : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
     
    /// @brief Retrieves the value by index
    /// This function checks the index validity, thowing an exception if the index is invalid....
    /// @param idx  [in] The desired index
    /// @see xxxxx
    ....

    et dans le .cpp
    Code c++ : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
     
    /// @internal Because we don't have the values yet, we are forcing lazy initialisation first
    ....


    La raison de l'utilisation de /// est simple, ca me permet de commenter... mes commentaires (avec un /* autour).

    Le @internal permet de rajouter des commentaires 'internes'... Ils seront générés dans la documentation interne (en 'debug'), mais pas dans la document publique (en 'release').
    Donc tout ce qui est 'privé' (dans le .cpp) n'est visible qu'en interne.
    Et tout ce qui est publique est généré dans la doc publique.
    N'oubliez pas de cliquer sur mais aussi sur si un commentaire vous a été utile !
    Et surtout

  7. #7
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    A vrai dire, doxygen a ceci qu'il est entièrement paramétrable.

    Cela signifie que tu peux tout à fait lui indiquer comme dossier à parcourir un dossier nommé... soyons simple: doxygen, avec des fichier d'extension .dox (ou n'importe quoi d'autre) qui ne contiendront que... des commentaires au format doxygen, et ce, de manière totalement indépendante des fichier d'en-tête et ou d'implémentation.

    Tout cela pour dire qu'il n'y a pas "de mauvaise solution", étant donné que doxygen les accepte toutes.

    Selon tes habitudes (avoir la description (reprise dans la doc) d'une méthode juste au dessus de son implémentation peut s'avérer intéressant) et/ou ton optique (tu veux du "closed source": tu compile donc ta bibliothèque/ ton application et tu génère toi même la doc, que tu fournis avec les en-têtes et la bibliothèque compilée ou au contraire tu veux tout l'inverse), tu reste tout à fait libre de faire strictement "à ta guise".

    Tu peux même envisager de placer une partie (les descriptions de fichiers) dans un fichier "séparé" (.dox), la description des classes dans le fichier d'en-tête et la description des méthodes/fonction dans le fichier d'implémentation... le tout sans aucun problème.

    Ce que j'aime avec l'idée de séparer réellement les commentaires nécessaires à la génération automatique de documentation du reste, c'est que cela se rapproche finalement fort d'autres outils utilisés, par exemple, sous linux...

    Mais bon, ce n'est là qu'un avis perso
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  8. #8
    Membre éprouvé Avatar de Spout
    Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    904
    Détails du profil
    Informations personnelles :
    Âge : 32
    Localisation : France, Val d'Oise (Île de France)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux

    Informations forums :
    Inscription : février 2007
    Messages : 904
    Points : 975
    Points
    975

    Par défaut

    Citation Envoyé par koala01 Voir le message
    Cela signifie que tu peux tout à fait lui indiquer comme dossier à parcourir un dossier nommé... soyons simple: doxygen, avec des fichier d'extension .dox (ou n'importe quoi d'autre) qui ne contiendront que... des commentaires au format doxygen, et ce, de manière totalement indépendante des fichier d'en-tête et ou d'implémentation.
    En fait c'est ça que je ne comprends pas. Si je mets mes commentaires doxygen juste au dessus des implémentations de mes fonctions, c'est parceque je ne vois pas comment il pourrait faire le lien entre les deux autrement. Dans le cas des classes ou des fichiers il n'y a pas ce problème vu qu'on indique explicitement ceux concernés (balises file et class).
    Ce qui n'est pas le cas dans les fonctions. Ou alors existe-t-il une balise doxygen function au même titre que class ou file que je ne connaitrais pas?
    "L'ordinateur obéit à vos ordres, pas à vos intentions." [Anonyme]

  9. #9
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    Doxygen travaille exactement comme un compilateur à une seule exception près: il n'oublie pas les symboles qu'il crées à chaque fichier.

    Cela signifie que, quand dans un fichier d'en-tête, il va rencontrer
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
     
    class MaClass
    {
        public:
            MaClass( int i);
            virtual ~MaClass();
    };
    il saura qu'il s'agit de
    • la définition de la classe MaClass
    • la déclaration de deux fonctions
      • le constructeur, qui prend un entier en argument
      • le destructeur


    Si, dans un fichier qui n'a rien à voir avec les .h(hpp) et les .cpp, il rencontre
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
     
    /** @file MaClass.h 
       * @brief header file including MaClass definition
       *
       * @author koala01
       * @ date 17/07/2008
       * ...
       */
     
    /** @class MaClass
       * @brief le joujou extra qui fait crac boum hue
       *
       * Les filles en tombent à mes genoux (merci Dutronc :D)
       */
    /** @fn MaClass::MaClass(int i)
       * @ brief ctor for MaClass
       *
       * ....
       */
     
    /** @fn MaClass::~MaClass()
       * @brief detor for MaClass
       *
       * ....
       */
    grace au @file, il saura que le commentaire se rapporte... au fichier MaClass.h, que la première ligne est la description breve de ce fichier, qu'il a été créé par koala01 le 17 juillet 2008.

    Grace au @class, il saura que ce qui suit fournit la description de... la classe MaClass, et grace au @fn, il saura que l'on fournit la description d'une fonction.

    Si, pour une raison ou une autre, il ne trouve pas le fichier, la définition de la classe ou la déclaration d'une des fonctions (mauvaise concordance des arguments, ou faute d'orthographe par exemple), tout comme le compilateur, il "t'enverra paitre" parce qu'il ne connais pas le symbole pour lequel tu fournis la description.

    Maintenant, tu peux tout aussi bien écrire ton code sous la forme de
    MaClass.h
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    /** @file MaClass.h 
       * @brief header file including MaClass definition
       *
       * @author koala01
       * @ date 17/07/2008
       * ...
       */
     
    /** @brief le joujou extra qui fait crac boum hue
       *
       * Les filles en tombent à mes genoux (merci Dutronc :D)
       */
    class MaClass
    {
        public:
            MaClass( int i);
            virtual ~MaClass();
    };
    /** @brief l'&eacute;numeration sympa
       *
       */
    enum etruc
    {
        val1, /// la premiere valeur
        val2, /// la deuxième valeur
        val3  ///la dernière valeur
    };
    MaClass.cpp
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    /** @file MaClass.cpp
       * @brief implementation file for MaClass
       *
       * @author koala01
       * @date 17/07/2008
       * ...
       */
     
    /** @ brief ctor for MaClass
       *
       * ....
       */
    MaClass::MaClass(int i) : i(i)
    {
    }
     
    /** @brief detor for MaClass
       *
       * ....
       */
    MaClass::~MaClass()
    {
    }
    cela ne lui posera aucun problème: la description (breve et normale) qu'il trouve s'applique soit à ce qui suit, soit à ce qui se trouve juste avant sur la même ligne...
    Je n'ai présenté qu'une infime partie des commandes que tu peux utiliser à l'intérieur des commentaires doxygen.

    Tu en trouvera la liste exhaustive dans le fichier %INSTALL PATH %/doxygen/html/commands.html
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  10. #10
    Membre éprouvé Avatar de Spout
    Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    904
    Détails du profil
    Informations personnelles :
    Âge : 32
    Localisation : France, Val d'Oise (Île de France)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux

    Informations forums :
    Inscription : février 2007
    Messages : 904
    Points : 975
    Points
    975

    Par défaut

    C'était le fn qu'il me manquait.
    Merci pour le lien de la doc, je n'avais jamais fait gaffe qu'elle était installée avec.
    "L'ordinateur obéit à vos ordres, pas à vos intentions." [Anonyme]

  11. #11
    Modérateur

    Homme Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    4 254
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : février 2007
    Messages : 4 254
    Points : 7 608
    Points
    7 608
    Billets dans le blog
    3

    Par défaut

    N'empeche que j'ai jamais rencontré un seul développeur qui, même en periode de rush, s'amuse à éditer 2 fichiers parcequ'il veut changer un paramètre...

    Déjà que la documentation inline est difficile à maintenir (on plante la compilation dès qu'il y a un warning doxygen), si on demande aux gens d'aller éditer deux fichiers (sans parler des merges éventuels qui en resulteront) c'est la fin des haricots (à mon sens).

    L'interêt d'avoir la documentation au dessus de la fonction permet plein de choses:
    1. Voir tout de suite les différence de déclaration sans avoir à comparer deux fichiers.
    2. Avoir la documentation "inline" quand la souris passe sur un des appels de fonctions) sans avoir à rebuilder toute la documentation (surtout que dox n'est pas un foudre de rapidité).
    3. Pouvoir faire un refactoring simple (renommage de fonction) sans avoir à chercher dans des fichiers doxygene...
    4. Eviter de se palucher la signature complete de chaque fonction / classe à nouveau

    Après pour tout le reste (pages, groups, etc...) des fichiers séparés sont 30x mieux...

    Mais bon... tout ça n'est qu'un avis personnel...
    N'oubliez pas de cliquer sur mais aussi sur si un commentaire vous a été utile !
    Et surtout

  12. #12
    Rédacteur
    Avatar de 3DArchi
    Profil pro
    Inscrit en
    juin 2008
    Messages
    7 636
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : juin 2008
    Messages : 7 636
    Points : 13 322
    Points
    13 322

    Par défaut

    Je partage l'avis de nicroman. L'intérêt de doxygen c'est quand même de pouvoir associer code et doc dans le même fichier. Si on commence à séparer la doc du code alors autant utiliser un éditeur quelconque pour faire de la doc (j'exagère un peu mais bon...).

  13. #13
    Rédacteur/Modérateur
    Avatar de JolyLoic
    Homme Profil pro
    Développeur informatique
    Inscrit en
    août 2004
    Messages
    5 353
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 42
    Localisation : France, Yvelines (Île de France)

    Informations professionnelles :
    Activité : Développeur informatique
    Secteur : High Tech - Éditeur de logiciels

    Informations forums :
    Inscription : août 2004
    Messages : 5 353
    Points : 14 852
    Points
    14 852

    Par défaut

    Et le problème d'avoir une documentation inline, c'est qu'elle rend la lecture "décontractée" du code moins simple. Surtout dans les headers, où le code peut vite être noyé.
    Ma session aux Microsoft TechDays 2013 : Développer en natif avec C++11.
    Celle des Microsoft TechDays 2014 : Bonnes pratiques pour apprivoiser le C++11 avec Visual C++
    Et celle des Microsoft TechDays 2015 : Visual C++ 2015 : voyage à la découverte d'un nouveau monde

  14. #14
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    Encore une fois, il y a à boire et à manger dans tous les arguments, mais je suis généralement de l'avis de JolyLoic.

    J'aurais tendance à estimer que les commentaires que l'on trouve dans le code ne devraient avoir pour seul but que de donner des précisions sur l'algorithme mis en oeuvre, et non sur le "comment utiliser cette fonction dans une application tierce", ce qui est quand même le but de doxygen...

    Il faut bien comprendre qu'il y a souvent plusieurs personnes qui interviennent dans le processus de création d'une application/bibliothèque:
    • Il y a celui "qui la rêve" (le client) qui se fout de la manière dont telle ou telle fonction doit être appelée et qui ne demande en gros à savoir que "si je fais ca, j'aurai tel résultat"... Tout ce qu'il lui faut à la limite, c'est un "how to" pour les différentes possibilités offertes par l'application
    • Il y a celui qui analyse les besoins qui doivent être remplis, et qui conçois éventuellement l'application / la bibliothèque: ce qu'il lui faut, c'est le nom des classes, celui des méthodes, les différentes relations, et, en quelques mots, les différents diagrammes permettant de comprendre l'application/la bibliothèque de manière globale
    • Il y a celui qui implémente la solution, ou qui modifie l'implémentation: ce qui l'intéresse, c'est surtout l'algorithme nécessaire au bon fonctionnement des différentes fonctions, même s'il et vrai que la manière de les appeler peut s'avérer intéressante (par contre, il n'a à la limite pas besoin de savoir "ce que fait" la fonction )
    • Il y a, enfin, celui qui va utiliser l'existant pour son usage personnel. Il a besoin de pouvoir se faire une idée globale des classes et des fonctions ainsi que de leur utilisation, et c'est - finalement - le seul à qui profite l'intégralité de la documentation que doxygen est susceptible de générer

    Je sais que certains préconnisent que les commentaires devraient représenter au total jusqu'à 1/3 du code, mais, quand on voit que l'ajout des commentaires doxygen représente parfois plus d'une vingtaine de ligne alors que le code équivalent n'en représente que... deux ou trois, on se rend compte qu'il arrive que le code soit réellement noyé dans les comm...

    Enfin, et pour répondre à nicroman, j'aurais tendance à dire que:
    1. les commentaires de documentation peuvent être écrits en fin d'implémentation (même si je ne le conseille pas forcément)
    2. avec les outils actuels, il est facile de retrouver un même texte dans plusieurs fichiers, et que, de toutes manières, la modifications des arguments d'un prototype impliquera des changements bien plus nombreux au niveau des appels de la fonction qu'au niveau de la documentation
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  15. #15
    Membre confirmé
    Homme Profil pro
    Développeur informatique
    Inscrit en
    juin 2007
    Messages
    311
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Gironde (Aquitaine)

    Informations professionnelles :
    Activité : Développeur informatique

    Informations forums :
    Inscription : juin 2007
    Messages : 311
    Points : 461
    Points
    461

    Par défaut

    Avec doxygen on peut faire une description brève (qui sera reprise dans la liste des objets éditée par doxygen) et une description détaillée (qui sera reprise dans dans la page consacré à l'objet). Une solution pourrait être de mettre la description brève (qui dit succinctement à quoi sert la fonction) dans le .h afin de ne pas l'alourdir excessivement, et la description détaillée (qui peut expliquer comment l'utiliser, et ainsi que des détails sur les algorithmes et les arguments) dans le .cpp.

    C'est sans doute la manière dont je vais procédé, dans la mesure où doxygen sera utilisée en interne, les sources seront accessibles aux utilisateurs. Mais c'est vrai que ça conviendra moins si l'objectif est une bibliothèque compilée, que l'utilisateur ne pourra pas parcourir avec doxygen.

  16. #16
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    Bienvenue sur le forum
    Citation Envoyé par Noxen Voir le message
    Avec doxygen on peut faire une description brève (qui sera reprise dans la liste des objets éditée par doxygen) et une description détaillée (qui sera reprise dans dans la page consacré à l'objet). Une solution pourrait être de mettre la description brève (qui dit succinctement à quoi sert la fonction) dans le .h afin de ne pas l'alourdir excessivement, et la description détaillée (qui peut expliquer comment l'utiliser, et ainsi que des détails sur les algorithmes et les arguments) dans le .cpp.

    C'est sans doute la manière dont je vais procédé, dans la mesure où doxygen sera utilisée en interne, les sources seront accessibles aux utilisateurs. Mais c'est vrai que ça conviendra moins si l'objectif est une bibliothèque compilée, que l'utilisateur ne pourra pas parcourir avec doxygen.
    Il ne faut pas oublier qu'il te reste aussi, dans le cas d'une bibliothèque compilée, la possibilité de générer toi même la doc avec doxygen et de la fournir dans l'archive qui contient les headers et la bibliothèque...

    Doxygen, bien que travaillant "lentement", est en définitive un outil suffisemment puissant pour te laisser la totale liberté de choix en ce qui concerne son utilisation... Il t'appartient finalement (comprenons nous sur le terme: il appartient à l'équipe de dev s'il s'agit de quelque chose développé de manière collégiale ) de choisir la politique qui te semble la meilleure (ou du moins la moins mauvaise )
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  17. #17
    Membre confirmé
    Homme Profil pro
    Développeur informatique
    Inscrit en
    juin 2007
    Messages
    311
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Gironde (Aquitaine)

    Informations professionnelles :
    Activité : Développeur informatique

    Informations forums :
    Inscription : juin 2007
    Messages : 311
    Points : 461
    Points
    461

    Par défaut

    C'est vrai que le point fort de cet outil est sa flexibilité. Que ce soit dans la syntaxe (Qt syle, Java style, autres...), dans la manière de commenter (dans les .h, dans des .cpp ou des .class, dans des .txt, avec des commentaires dans les entités ou à l'extérieur ...) dans le type de langage (C++, C#, Java ...) ou encore dans le type de sortie (HTML, LaTeX, RTF, Man, XML ...). Cet outil est en fait paramétrable à loisir afin de correspondre précisément aux besoin de l'utilisateur. A la limite, ça peut même être assez déroutant quand on le découvre, il faut arriver à se fixer des limites pour unifier son travail et son style d'utilisation, et ne pas partir dans tous les sens.

  18. #18
    Modérateur

    Homme Profil pro
    Ingénieur systèmes et réseaux
    Inscrit en
    février 2007
    Messages
    4 254
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Localisation : France, Rhône (Rhône Alpes)

    Informations professionnelles :
    Activité : Ingénieur systèmes et réseaux
    Secteur : High Tech - Multimédia et Internet

    Informations forums :
    Inscription : février 2007
    Messages : 4 254
    Points : 7 608
    Points
    7 608
    Billets dans le blog
    3

    Par défaut

    Oui il est très souple... et très facile à interfacer/intégrer avec de nombreux IDEs...

    D'ailleurs... pour répondre à une remarque sur la lisibilité des headers après "doxygenisation", je dirai que le but de la documentation est justement de ne pas avoir à ouvrir les headers... mais bon...

    Chacun fait comme il veut de toute manière...
    N'oubliez pas de cliquer sur mais aussi sur si un commentaire vous a été utile !
    Et surtout

  19. #19
    Membre du Club
    Profil pro
    Inscrit en
    mai 2007
    Messages
    69
    Détails du profil
    Informations personnelles :
    Localisation : France

    Informations forums :
    Inscription : mai 2007
    Messages : 69
    Points : 64
    Points
    64

    Par défaut

    Merci pour vos réponses.

    Je crois que je vais continuer à faire comme avant, garder tout les commentaires dans le .cpp. J'avais peur que ça devienne illisible mais comme je m'impose de ne pas dépasser 3 lignes de texte de commentaire pour décrire une fonction (toujours au début de la fonction), tout devrait aller.

  20. #20
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    Consultant informatique
    Inscrit en
    octobre 2004
    Messages
    10 464
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 45
    Localisation : Belgique

    Informations professionnelles :
    Activité : Consultant informatique

    Informations forums :
    Inscription : octobre 2004
    Messages : 10 464
    Points : 22 702
    Points
    22 702

    Par défaut

    La question à se poser est alors: es tu sur que tu saura respecter cette limite de trois lignes que tu te fixe" arbitrairement"

    D'autant plus que, ainsi que j'ai essayé de le faire comprendre, il y a des chances pour que tu en arrive à vouloir donner des précisions sur l'algorithme de certaines fonctions que tu va implémenter... précisions qui seront des commentaires utiles dans le code, mais qu'il n'est a priori pas nécessaire de placer dans la documentation générée par doxygen

    Le tout, c'est sans compter que, idéalement, il semble utile/opportun de donner une explication pour chaque argument des différentes fonctions ainsi que sur leur retour et / ou sur les exceptions qu'elles peuvent lancer dans la documentation
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

+ Répondre à la discussion
Cette discussion est résolue.
Page 1 sur 2 12 DernièreDernière

Discussions similaires

  1. Lister les headers inclus dans module kernel (.ko)
    Par 1rageux dans le forum Linux
    Réponses: 0
    Dernier message: 11/07/2011, 13h30
  2. Réponses: 1
    Dernier message: 21/11/2009, 13h03
  3. Réponses: 2
    Dernier message: 16/06/2009, 16h04
  4. Réponses: 3
    Dernier message: 26/09/2008, 17h52
  5. Réponses: 3
    Dernier message: 04/07/2008, 12h00

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo