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.