Bonjour à toutes et tous,

Ne trouvant pas comment faire, je me tourne vers vous. Je veux mettre en place une bonne documentation pour mon code, mais n'ayant pas vu ça à l'IUT je ne sais pas vraiment où la mettre.

La faire est assez simple mais voilà, doit on faire un bloc de documentation par donnée membre et par fonction dans le .h, exemple :

/**
  * @file   UneClasse.h
  *
  * @author moi
  *
  * @date   aujourd'hui
  *
  * @brief  une question de documentation
  */

#ifndef __UNECLASSE_H__
#define __UNECLASSE_H__

#include <MesIncludes>

namespace nsMySpace
{
/**
  * @class UneClasse UneClasse.h "UneClasse.h"
  * @brief Classe qui sert d'exemple
  *
  * Classe ayant quelques donnees-membres et quelques fonctions-membres
  */
     class UneClasse
     {
         /**
          * @var   m_donneeMembre1;
          * @brief une donnée membre
          *
          */
         type m_donneeMembre1;

       public :
         /**
          * @brief une autre donnée membre
          *
          */
         type m_donneeMembre2;

       public :
         /**
          * @brief Constructeur par defaut
          *
          * @param donneeMembre1 : 1er donnée
          * @param donneeMembre2 : 2e donnée
          *
          */
         UneClasse(type donneeMembre1 = QuelqueChose, type donneeMembre1 = QuelqueChose);

         /**
          * @brief Destructeur
          *
          */
         ~UneClasse(void);

     }; // UneClasse
}
#endif /* __UNECLASSE_H__*/

Donc voilà, est-ce que c'est bien comme ça que l'on faire dans le .h? Un bloc par donnée et fonction membre, et doit on mettre un bloc de documentation dans les .cpp pour chaque fonction aussi? ou uniquement dans le .cpp / .h

Voilà je ne sais pas du tout où mettre les blocs comme vous l'aurai compris .

Merci.

-
Edité par armadon13127 31 mai 2013 à 9:46:34

@class, @var, @function, etc ne servent à rien (à part alourdir un truc qui est déjà très lourd)

@brief est lourd aussi. Je préfère le mode AUTOBRIEF (à régler dans le doxyfile), avec la première ligne qui doit impérativement se terminer par un point (vim a une excellente coloration syntaxique pour ne pas se faire avoir)

La syntaxe de @param, c'est "@param NomDuParamètre explications sur plusieurs lignes". Les ':' ne servent à rien. Génère une doc pour voir cela. En revanche, @param[in], @param[out] et @param[in,out] sont très utiles.

D'autres champs extrêmement utiles au niveau documentation de classes et de fonctions  sont @invariant, @pre et @post.

Au niveau global, j'utilise aussi beaucoup les groupes. Je tends à trouver une doc doxygen sans groupes vite inexploitable.

Pour ta dernière question: pas besoin de dupliquer la doc dans le .cpp

Hormis brief et class qui sont malheureusement imposées inutilement, pour moi un code doxygéné ressemble à cela : http://hg.orfeo-toolbox.org/OTB/file/80062157befb/Code/UtilitiesAdapters/OGRAdapters/otbOGRLayerWrapper.h
Et ceci est le résultat: http://www.orfeo-toolbox.org/doxygen/classotb_1_1ogr_1_1Layer.html (généré sans le report des zones briefs :()

-
Edité par lmghs 30 mai 2013 à 17:49:20