Discussion :

[AlKoLiK]

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 !

[Médinoc]

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...

[koala01]

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

[loufoque]

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.

[Spout]

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.

[nicroman]

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.

[koala01]

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

[Spout]

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?

[koala01]

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'é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

[Spout]

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.

[nicroman]

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...

[3DArchi]

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...).

[JolyLoic]

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é.

[koala01]

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

[Noxen]

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.

[koala01]

Bienvenue sur le forum

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 )

[Noxen]

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.

[nicroman]

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...

[AlKoLiK]

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.

[koala01]

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