Discussion :

[Ripstone]

Bonjour à tous

alors voila pas moyen de trouver une reponse je vous expose d'abord un code

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
/*!
 * \file test.h
 * \brief This header file contains definitions of the interface
 * \version 1.0
 */
 
class Test
{
  public:
    enum TEnum { Val1, Val2 };
 
    /*! Another enum, with inline docs */
    enum AnotherEnum 
    { 
      V1, /*!< value 1 */
      V2  /*!< value 2 */
    };
};
enum alone_In_The_Class { var1 , var2 };
 
 
 
/*! \class Test
 * The class description.
 */
 
/*! \enum Test::TEnum
 * A description of the enum type.
 */
 
/*! \var Test::TEnum Test::Val1
 * The description of the first enum value.
 */
 
 /*! \var Test::TEnum Test::Val2
 * The description of the second enum value.
 */
 
/*! \enum ::alone_In_The_Class
 * A description of the enum type.
 */
 
 /*! \var ::alone_In_The_Class ::var1
 * The description of the first enum value.
 */
 
 /*! \var ::alone_In_The_Class ::var2
 * The description of the second enum value.
 */

Mon problème est que aucune documentation n'est généré pour le enum alone_In_The_Class ce qui est très embêtant et pas moyen de trouver une solution sans faire un truc moche.

voici en gros la solution que j'ai trouvé:

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
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
 
/*!
 * \file SVMGRAPI2.h
 * \brief This header file contains definitions of the interface
 * methods that must be implemented by a SV manager and the API
 * provided by SV32 to write a SV manager.
 * \version 9.0
 */
 
/*!
 * \mainpage manager API
 *
 * test
 
 * \page Enumerations Enumerations
 * - \subpage alone_In_The_Class Enumerates the variable types
 */
 
class Test
{
  public:
    enum TEnum { Val1, Val2 };
 
    /*! Another enum, with inline docs */
    enum AnotherEnum 
    { 
      V1, /*!< value 1 */
      V2  /*!< value 2 */
    };
};
 
 
 
/*! \class Test
 * The class description.
 */
 
/*! \enum Test::TEnum
 * A description of the enum type.
 */
 
/*! \var Test::TEnum Test::Val1
 * The description of the first enum value.
 */
 
 /*! \var Test::TEnum Test::Val2
 * The description of the second enum value.
 */
 
 
 /*!
 * \page alone_In_The_Class alone_In_The_Class
 *
 * alone_In_The_Class contains the list of all possible alone_In_The_Class var.
 * 
 * \par Values
 *- var1: the first variable
 *- var2: The second variable
 *
 */
 enum alone_In_The_Class { var1 , var2 };

le problème c'est qu'il faut tout faire à la main pour une dizaine d'enum je veux bien mais la je pars sur beaucoup plus !


[edit 11:04] petite précision, mon problème viens des enum en dehors d'une classe.

Si quelqu'un a une idée je vous remercie.

[Mac LAK]

Quelle version de Doxygen utilises-tu ? Sous quelle plate-forme ?

[Ripstone]

Quelle version de Doxygen utilises-tu ? Sous quelle plate-forme ?

effectivement je ne précise pas! honte à moi.

j'utilise la dernière version 1.6 et j' ai également fait des tests avec la 1.5 le tout sous Windows Xp

[koala01]

Salut, et bienvenue sur le forum.

Quitte à mettre les commentaire doxygen dans tes fichiers d'en-tête ou d'implémentation, pourquoi ne pas les placer à chaque fois au dessus de la classe ou de la fonction qu'ils documentent

En effet, il est toujours plus logique d'avoir les informations concernant une classe, une énumération ou une fonction avant d'avoir perdu son temps à essayer de comprendre le code

Un code proche de

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
28
29
30
31
32
33
34
35
36
37
38
39
/*!
 * \file test.h
 * \brief This header file contains definitions of the interface
 * \version 1.0
 * 
 * Ceci donne des information sur le contenu du fichier
 */
 
/*! \brief l'interface de la mort qui tue
 * The class description.
 * 
 * Tant qu'à faire,le lecteur du code a aussi le droit de savoir 
 * de quoi il retourne :D
 */
 
class Test
{
  public:
    /*! \brief la description breve de l'énumération
     * 
     * A description of the enum type.
     */
 
    enum TEnum { Val1, Val2 };
 
    /*! \brief et une autre
     * 
     */
    enum AnotherEnum 
    { 
      V1, /*!< value 1 */
      V2  /*!< value 2 */
    };
};
/*! \brief cette enumeration est hors de toute classe
 *
 * elle va servir pour ...
 */
enum alone_In_The_Class { var1 , var2 };

aura le double intérêt de permettre à doxygen de travailler sans problème et de permettre au lecteur du code d'avoir une description du code qu'il va lire avant d'avoir perdu son temps à essayer de le déchiffrer

Pense aussi toujours bien à placer une description brève, soit en ajoutant une ligne \brief (suivie d'une ligne vide), soit en configurant doxygen de manière à ce qu'il considère toujours la première ligne comme étant la description brève.

Cela te permettra d'obtenir cette description brève sur la partie droite des tableaux récapitulatifs

L'autre solution, qui fait encore débat, consiste à créer un fichier clairement séparé pour les commentaires doxygen.

Si cette solution fait débat, c'est parce que d'aucuns estiment (pas tout à fait à tord) qu'il est plus facile de maintenir la documentation à jour s'il n'y a qu'un seul fichier à modifier

Tu peux donner n'importe quelle extension à ce fichier séparer, mais, l'un dans l'autre, l'extension ".dox" semble "pas mal" pour un fichier... doxygen

L'idée est donc de séparer tes fichiers ".dox" dans un dossier qui ne sert qu'à cela et de configurer doxygen de manière à ce qu'il parcoure le dossier en question en générant la documentation sur base des fichiers "*.dox" (si tu utilises l'assistant, tu peux faire tout cela dans la partie "expert" )

Ton code source ressemblera alors à

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
/* nous avons supprimé tous les commentaires doxygen, ce qui ne nous
 * empêche absolument pas d'avoir des commentaire qui ne serve pas à la
 * génération de la documentation ;)
 */
class Test
{
  public:
 
    enum TEnum { Val1, Val2 };
    enum AnotherEnum 
    { 
      V1,
      V2
    };
};
enum alone_In_The_Class { var1 , var2 };

et tu aura par ailleur un fichier que nous nommerons Test.dox, ca semble pas mal , qui ressemblera à

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
28
29
30
31
32
/*!
 * \file test.h chemin/vers/test.h
 * \brief This header file contains definitions of the interface
 * \version 1.0
 * 
 * Ceci donne des information sur le contenu du fichier
 */
 
/*! \class Test
 *  \brief l'interface de la mort qui tue
 *
 * The class description.
 * 
 */
 
/*! \enum Test::TEnum
 *  \brief la description breve de l'énumération
 * 
 * A description of the enum type.
 */
 
/*! \enum Test::AnotherEnum 
 *  \brief la description breve de l'énumération
 * 
 * A description of the enum type.
 */
 
/*! \enum alone_In_The_Class
 *  \brief la description breve de l'énumération
 * 
 * A description of the enum type.
 */

[Ripstone]

Merci koala01 pour la réponse

J'ai repris votre code, il se trouve que j'écris effectivement mes commentaire dans mon fichier comme vous me le dites.

J'ai repris votre code est généré la documentation et je n'ai aucune trace de l'enum alone_In_The_Class dans ma doc.

Petite précision je fais de l'html compilé.

[koala01]

Merci koala01 pour la réponse

J'ai repris votre code, il se trouve que j'écris effectivement mes commentaire dans mon fichier comme vous me le dites.

Tu peux me (nous) tutoyer...

Je me doute que cela part simplement d'une bonne éducation, mais je ne suis pas noble, et je ne me sens pas vieux assez pour être vouvoyé

En plus, le "tu" est plus facile à l'emploi

J'ai repris votre code est généré la documentation et je n'ai aucune trace de l'enum alone_In_The_Class dans ma doc.

Petite précision je fais de l'html compilé.

Les énumérations ont la sale manie de se planquer dans la documentation doxygen...

Fais peut être un tour du coté de la liste des symboles définis ou du coté de la documentation propre au fichier... Elle devrait se trouver "quelque part par là"

[Ripstone]

Donc je viens de regarder et je ne trouve vraiment pas l'énumération alone_In_The_Class

Je vous ai fourni mon dossier de test avec ma configuration de doxygen + le repertoire html généré soit sa viens de ma compilation soit y a vraiment un truc que j'ai pas compris


Merci pour l'aide

[Mac LAK]

Déjà, elle est bien parsée et vue : en l'ajoutant de force à un module (via \defgroup et \ingroup), ton énumération apparaît correctement dans la documentation.

Reste que, par défaut, elle n'apparaît effectivement pas, et/ou je n'ai pas trouvé le réglage qui le permettrait malgré les tripatouillages d'à peu près tout ce qui concerne la visibilité dans les options.

[Ripstone]

Ok merci pour les réponses je vais me débrouiller avec les \defgroup et \ingroup

Si quelqu un a la autre solution je suis preneur
Merci à tous pour votre aide

[Mac LAK]

Éventuellement, tu peux remonter le bug à Dimitri Van Heesch sur le site Doxygen aussi, afin qu'il soit corrigé.

Bon courage !

[Ripstone]

Ok je remonte le bug
oh cas ou je remonte la réponse dans le forum