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 !
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 !
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.
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
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.
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:
Exemple que de ce que je fais au quotidien: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.
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_HEst-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.
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) { .... } //------------------------------
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.
Partager