comment utiliser Doxygen

Version imprimable

18/06/2012, 11h23
ssssa1983

comment utiliser Doxygen

Bonjour,

Je viens de decouverir doxygen et j'aimerais bien l'utiliser pour faire la documentation de mes programmes.
Est ce qu'il ya quelqu'un pour m'expliquer l'utilisation de doxygen en utilisant un exemple facile?
Je vous remercie en avance.
18/06/2012, 12h37
gbdivers

Bonjour

C'est une question très généraliste que tu poses là. La documentation de dixygen ne te semble pas claire et abordable ? http://www.stack.nl/~dimitri/doxygen/manual.html
18/06/2012, 12h44
mala92

Citation:

Envoyé par gbdivers

Bonjour

C'est une question très généraliste que tu poses là. La documentation de dixygen ne te semble pas claire et abordable ? http://www.stack.nl/~dimitri/doxygen/manual.html

Salut,

Si un modérateur passait par là, il te dirait d'utiliser en priorité les liens "locaux". (à prendre au 2nd degré, hein ?) :pastaper:
http://franckh.developpez.com/tutoriels/outils/doxygen/
18/06/2012, 12h57
gbdivers

Citation:

Envoyé par mala92

Salut,

Si un modérateur passait par là, il te dirait d'utiliser en priorité les liens "locaux". (à prendre au 2nd degré, hein ?) :pastaper:
http://franckh.developpez.com/tutoriels/outils/doxygen/

Merci, je savais qu'il y avait un tutoriel mais je ne l'ai pas retrouvé
Pour les liens, on n'a jamais interdit tous les liens externe :) En particulier, les liens vers la doc d'une libs ne posent pas de problème
18/06/2012, 13h54
ssssa1983

Oui, je suis d'accord avec vous.
la premiere chose, je suis null en anglais, je ne comprends pas grande chose.....
J'ai déjà essayé de suivre quelques tutoriels, mais j'arrive pas à comprendre.

pour être précise: Est ce que c'est obligé d'utiliser les balises dans notre programme ou le logiciel sait tout faire?
18/06/2012, 14h10
mala92

Citation:

Envoyé par gbdivers

Pour les liens, on n'a jamais interdit tous les liens externe :)

C'est pour ça que j'ai dit "en priorité" et pas "interdit". ;)

Citation:

pour être précise: Est ce que c'est obligé d'utiliser les balises dans notre programme ou le logiciel sait tout faire?

Les logiciels ne sont pas devin. Il faut les guider. Dans le cas de doxygen et tous ses "concurrents", il faut mettre des balises, mais pas dans le code, juste dans les commentaires décrivant les fonctions.
Doxygen sait comment est structurée une classe C++, il peut donc générer une doc sans la moindre balise, mais ta doc ne sera pas "propre".

Merci pour vos réponses,

voilà un exemple simple que j'ai fait, mais malheureusement il me donne rien du tout.

Code:

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
/**
 * \file Prise_Origine.cpp
 * \brief .
 * \author toto
 * \version 0.1
 * \date 16 juin 2012
 *
 * Programme determine l'orine du repere.
 *
 */
 
 
#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
 
 
#define MAX 4
 
/**
 * \fn int main()
 * \brief Entrée du programme.
 *
 * \return 0 - Arrêt normal du programme.
 */
 
int main()
{
int  fd[MAX], i;
 
fd[0] = open("/dev/ttyS0", O_WRONLY | O_NDELAY);
if (fd[0] == -1)
     printf("Une erreur est survenue lors de la connexion avec le port serie 1.Les informations ne lui seront donc pas transmises fd0.");
 
fd[1] = open("/dev/ttyS1", O_WRONLY | O_NDELAY);
if (fd[1] == -1)
     printf("Une erreur est survenue lors de la connexion avec le port serie 1.Les informations ne lui seront donc pas transmises.fd1");
 
fd[2] = open("/dev/ttyS2", O_WRONLY | O_NDELAY);
if (fd[2] == -1)
     printf("Une erreur est survenue lors de la connexion avec le port serie 1.Les informations ne lui seront donc pas transmises.fd2");
 
fd[3] = open("/dev/ttyS3", O_WRONLY | O_NDELAY);
if (fd[3] == -1)
     printf("Une erreur est survenue lors de la connexion avec le port serie 1.Les informations ne lui seront donc pas transmises.fd3");
 
else
        for (int i = 0; i < MAX; i++)
 
        {
          if (fd[i])
          {
             write(fd[i], "OPMODE 8\r",9);
             write(fd[i], "EN\r",3);
             write(fd[i], "MH\r",3);
             write(fd[i], "PFB\r",4);
             write(fd[i], "DIS\r",4);
 
          }
        }
 
 
return 0;
 
}

as-tu les cpp dans FILE_PATTERNS de ton fichier de configuration de doxygen.
Ex :

Code:

1
2
3
4
5
6
FILE_PATTERNS          = *.h \
                         *.hh \
                         *.hxx \
                         *.hpp \
                         *.c \
                         *.cpp

19/06/2012, 01h25
Luc Hermitte

\fn, \class, \namespace, \struct et compagnie ne servent à que dalle.
\brief a un intérêt très limité. Je suis convaincu que le mode AUTOBRIEF est de loin préférable pour garder une doc claire.

Sont importants:
- tous les tags pour grouper la doc (une doc non grouptée est vite illisible et inexploitable) -> \group, \ingroup, \defgroup
- \param et ses décorateurs [in], [out], [in,out]
- \return -- pour dire autre chose que le nom du type renvoyé
- \throw -- même, et surtout pour dire quand une fonction ne lêve autre exception
- \pre, \post, et \invariant pour détailler le contrat des classes et fonction

Sont pratiques:
- \note, \warning
- \since
- \c
- %
- \code ... \endcode
- et tous les tags HTML

Bref, il faut lire la doc. Elle est très simple.

Citation:

Envoyé par mala92

as-tu les cpp dans FILE_PATTERNS de ton fichier de configuration de doxygen.
Ex :

Code:

1
2
3
4
5
6
FILE_PATTERNS          = *.h \
                         *.hh \
                         *.hxx \
                         *.hpp \
                         *.c \
                         *.cpp

Oui j'ai trouvé quelque chose comme ça......
ça veut dire quoi??

19/06/2012, 12h10
Neckara

Tout simplement que doxygen va regarder tous les fichier se terminant par .cpp, .h, .... pour générer la documentation.

'*' signifie qu'on peut avoir n'importe quoi.
Le '\' sert à dire qu'il y a une autre ligne à la suite.
20/06/2012, 09h58
ssssa1983

Bonjour,

vous me parler comme quelqu'un qui paitrise Doxygen. apparemment je me suis trompé d'écrire mon sujet avec les débutant.
Si vous pensez que j'ai compris quelque chose vous vous trompez, jusqu'à maintenant je n'ai rien compris.

comme je vous ai dit je suis débutant, je ne comprends ce que'il faut faire. j'ai besoin des exemples pour comprendre. (je suis quelqu'un qui ne comprend que avec les exemples, désolé mais je suis comme ça).

Merci pour votre compréhension.

Les liens donné te donnent des exemples :

Citation:

Envoyé par http://franckh.developpez.com/tutoriels/outils/doxygen/#LIII-E

Code:

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
#ifndef CPLAYER_H_
#define CPLAYER_H_
 
/*!
 * \file CPlayer.h
 * \brief Lecteur de musique de base
 * \author hiko-seijuro
 * \version 0.1
 */
#include <string>
#include <list>
 
/*! \namespace player
 * 
 * espace de nommage regroupant les outils composants 
 * un lecteur audio
 */
namespace player
{
  /*! \class CPlayer
   * \brief classe representant le lecteur
   *
   *  La classe gere la lecture d'une liste de morceaux
   */
  class CPlayer
  {
  private:
    std::list<string> m_listSongs; /*!< Liste des morceaux*/
    std::list<string>::iterator m_currentSong; /*!< Morceau courant */
 
 
  public:
    /*!
     *  \brief Constructeur
     *
     *  Constructeur de la classe CPlayer
     *
     *  \param listSongs : liste initial des morceaux
     */
    CPlayer(std::list<string> listSongs);
 
    /*!
     *  \brief Destructeur
     *
     *  Destructeur de la classe CPlayer
     */
    virtual ~CPlayer();
 
  public:
    /*!
     *  \brief Ajout d'un morceau
     *
     *  Methode qui permet d'ajouter un morceau a liste de
     *  lecture
     *
     *  \param strSong : le morceau a ajouter
     *  \return true si morceau deja present dans la liste,
     *  false sinon
     */
    bool add(std::string strSong);
 
    /*!
     *  \brief Morceau suivant
     *
     *  Passage au morceau suivant
     */
    void next();
 
    /*!
     *  \brief Morceau precedent
     *
     *  Passage au morceau precedent
     */
    void previous();
 
    /*!
     *  \brief Lecture 
     *
     *  Lance la lecture de la liste
     */
    void play();
 
    /*!
     *  \brief Arret
     *
     *  Arrete la lecture
     */
    void stop();
  };
};
 
#endif

Tu as aussi tout ce qu'il faut faire une fois les commentaires écris : http://franckh.developpez.com/tutori...s/doxygen/#LIV

EDIT : tu n'es pas obligé d'utiliser le caractère '\', tu peux aussi utiliser '@' à la place : @brief, @return, @param ... Après ce n'est qu'une question d'esthétique.

20/06/2012, 10h45
Luc Hermitte

Au détail que \class et \brief sont exigés par les règles stylistiques (car, je le répète, ils ne servent à rien), une doxygénation de fichier ressemble à ça pour moi: OTB/otbOGRDataSourceWrapper.h

Merci pour votre compréhension,

j'ai déjà rajouté les commentaire pour le fichier.h
est ce que je doit rajouter les commentaires pour son fichier.cpp? si oui comment?

Voici un exemple de mon programme
comedi.hh

Code:

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
#ifndef		__COMEDI_HH__
#define		__COMEDI_HH__
 
#include	<comedilib.h>
/*!
   * \file  Comedi.hh
   * \brief comminucation avec comedi
   * \date 18 juin 2012
   * \author Saïd.B
  */
class		Comedi
{
 
  int		_subdev;   /*!< _subdev est un entier */      /* change this to your input subdevice */
  int		_chan;     /*!< _chan est un entier */     /* change this to your channel */
  int		_range;    /*!< _range est un entier */
  comedi_range	*_range_comedi;
  lsampl_t	_maxdata;
  int		_aref;      /*!< _aref est un entier */
 
  comedi_t	*_it;
  lsampl_t	_data;
 
public:
 
  /*!
       *  \brief Constructeur
       *
       *  Constructeur de la classe Comedi
       *
   */
  Comedi();
 
  /*!
       *  \brief Destructeur
       *
       *  Destructeur de la classe Comedi
   */
  ~Comedi();
 
  /*! \fn void            send(double value)
   * \brief send(value) envoi de la valeur par comedi.
   * \param value est un double
   */
 
  void		send(double value);
};
 
#endif		/* __COMEDI_HH__ */

comedi.cpp

Code:

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
28
29
30
31
32
33
34
 
#include	<iostream>
#include	"comedi.hh"
 
Comedi::Comedi()
  : _subdev(1), _chan(0), _range(0), _aref(AREF_GROUND)
{
  // Ouverture du flux de comedi
  _it = comedi_open("/dev/comedi0");
  // Initialise Comedi
  if (_it > 0)
    {
      _range_comedi = comedi_get_range(_it, _subdev, _chan, _range);
      _maxdata = comedi_get_maxdata(_it, _subdev, _chan);
    }
  else
    std::cout << "Erreur a l'ouverture du flux de comedi" << std::endl;
}
 
Comedi::~Comedi()
{
}
 
// Envoi de la valeur par comedi
void		Comedi::send(double value)
{
  double        coef = 1.0;
  if (_it > 0)
    {
      value = 1 + (coef * (value - 1));
      _data = comedi_from_phys(value * 2 / 5, _range_comedi, _maxdata);
      comedi_data_write(_it, _subdev, 0, _range, _aref, _data);
    }
}

Merci en avance

20/06/2012, 14h59
Luc Hermitte

- \file et \class n'ont pas à être mélangés
- \class ne sert à rien. \fn c'est pareil -> DRY!
- \brief se remplace avantageusement par un point final, et l'option AUTOBRIEF à vrai
- donner le type d'un paramètre dans \param n'a aucun intérêt car c'est déjà écrit à côté. C'est fait pour expliquer à quoi sert le paramètre
- pareil pour les variables membres.
- il est évident qu'il s'agit du constructeur de la classe Comedi

Doxygen, c'est facile => toujours générer la doc associée à notre code et regarder le résultat obtenu. C'est là que l'on voit que rappeler les types des I/O et des variables n'a strictement aucun intérêt (de même que les fioritures comme les deux-points). Il suffit de lever les yeux de 2cm pour avoir l'info.
La doc, c'est fait pour expliquer à quoi servent les choses, comment on s'en sert, et qu'elles sont les contraintes d'utilisation.

BTW, le préfixage des trucs à nous par un tiret-bas est globalement déconseillé en C et C++ -> cf FAQ.
20/06/2012, 15h23
ssssa1983

Merci pour ta réponse,

Après des recherches et vos réponses, j'arrive à mieux comprendre. Mais je reste toujours débutant.

Merci à tous